|
|
@@ -1,176 +1,91 @@
|
|
|
# Agent Guidelines
|
|
|
|
|
|
-This document provides guidelines for AI agents working in this repository.
|
|
|
-
|
|
|
## Project Overview
|
|
|
|
|
|
-This is a minimal repository. When adding new projects, document their structure here.
|
|
|
+Minimal placeholder repository. No build system, no source code yet. Two Chinese-named directories:
|
|
|
+- `模版文件/` — Template files (currently empty)
|
|
|
+- `需求材料/` — Requirement materials (contains 艾灸椅功能定义-最新.xlsx — moxibustion chair feature spec)
|
|
|
|
|
|
## Build / Lint / Test Commands
|
|
|
|
|
|
-Since the project currently has no build system, these are placeholder guidelines:
|
|
|
+**None configured.** This repo has no `package.json`, `Makefile`, `pyproject.toml`, or any build configuration.
|
|
|
+
|
|
|
+When a project is added, document commands here. Common patterns:
|
|
|
|
|
|
```bash
|
|
|
-# Running a single test (example patterns - adjust per project)
|
|
|
-npm test -- --testPathPattern=filename
|
|
|
-pytest tests/test_file.py::TestClass::test_method
|
|
|
-cargo test test_name
|
|
|
+# Node.js / npm
|
|
|
+npm install # install deps
|
|
|
+npm run dev # dev server
|
|
|
+npm run build # production build
|
|
|
+npm test # run all tests
|
|
|
+npm test -- --testPathPattern=filename # single test
|
|
|
+
|
|
|
+# Python
|
|
|
+pip install -r requirements.txt
|
|
|
+pytest tests/test_file.py::TestClass::test_method # single test
|
|
|
+pytest -k test_name # single test by name
|
|
|
+
|
|
|
+# Go
|
|
|
+go build ./...
|
|
|
go test -run TestName ./...
|
|
|
|
|
|
-# Linting
|
|
|
-npm run lint
|
|
|
-eslint src/
|
|
|
-pylint src/
|
|
|
-golangci-lint run
|
|
|
-
|
|
|
-# Building
|
|
|
-npm run build
|
|
|
-npm run dev
|
|
|
+# Rust
|
|
|
cargo build
|
|
|
+cargo test test_name
|
|
|
```
|
|
|
|
|
|
## Code Style Guidelines
|
|
|
|
|
|
-### Imports
|
|
|
+**No code exists yet.** When adding code, follow these defaults unless project-specific configs dictate otherwise:
|
|
|
|
|
|
-- Use absolute imports over relative imports when possible
|
|
|
-- Group imports: standard library, third-party, local
|
|
|
+### Imports
|
|
|
+- Group: stdlib → third-party → local
|
|
|
- Sort alphabetically within groups
|
|
|
-- Use explicit imports rather than wildcard imports
|
|
|
+- Use explicit imports, no wildcards
|
|
|
|
|
|
### Formatting
|
|
|
+- Match existing file indentation (2 or 4 spaces)
|
|
|
+- Max line length: 80-120 chars
|
|
|
+- Consistent line endings (CRLF on Windows, LF elsewhere)
|
|
|
|
|
|
-- Use 2 or 4 space indentation (match existing project style)
|
|
|
-- Maximum line length: 80-120 characters (per project)
|
|
|
-- Add trailing commas where appropriate
|
|
|
-- Use consistent line endings (LF or CRLF per project)
|
|
|
-
|
|
|
-### Types
|
|
|
-
|
|
|
-- Prefer explicit type annotations for function parameters and return types
|
|
|
-- Use interfaces/types for object shapes
|
|
|
-- Avoid `any` type - use `unknown` if type is truly unknown
|
|
|
-- Enable strict type checking where possible
|
|
|
-
|
|
|
-### Naming Conventions
|
|
|
-
|
|
|
-- **Files**: kebab-case or PascalCase (match project)
|
|
|
-- **Classes**: PascalCase (e.g., `UserService`)
|
|
|
-- **Functions/Variables**: camelCase (e.g., `getUserById`)
|
|
|
-- **Constants**: SCREAMING_SNAKE_CASE (e.g., `MAX_RETRIES`)
|
|
|
-- **Booleans**: Use `is`, `has`, `should` prefixes (e.g., `isActive`)
|
|
|
+### Naming
|
|
|
+- **Files**: kebab-case or PascalCase
|
|
|
+- **Classes**: PascalCase (`UserService`)
|
|
|
+- **Functions/Vars**: camelCase (`getUserById`)
|
|
|
+- **Constants**: SCREAMING_SNAKE_CASE (`MAX_RETRIES`)
|
|
|
+- **Booleans**: `is`/`has`/`should` prefix (`isActive`)
|
|
|
|
|
|
### Error Handling
|
|
|
+- Use specific error types, not generic
|
|
|
+- Include context in error messages
|
|
|
+- Never silently swallow errors
|
|
|
|
|
|
-- Use specific exception types rather than generic ones
|
|
|
-- Include meaningful error messages with context
|
|
|
-- Log errors with appropriate level (error, warning, debug)
|
|
|
-- Handle async errors with try/catch or .catch()
|
|
|
-- Never silently swallow errors unless explicitly intended
|
|
|
+### Types (if TypeScript)
|
|
|
+- Explicit annotations on params and returns
|
|
|
+- Avoid `any` — use `unknown` if truly unknown
|
|
|
+- Enable strict mode
|
|
|
|
|
|
-### General Practices
|
|
|
-
|
|
|
-- Keep functions small and focused (single responsibility)
|
|
|
-- Write comments for "why", not "what"
|
|
|
-- Keep code DRY (Don't Repeat Yourself)
|
|
|
-- Use meaningful variable and function names
|
|
|
-- Write tests for new features
|
|
|
-- Follow the existing code style of the project
|
|
|
-
|
|
|
-## Testing Guidelines
|
|
|
+## Working with This Repository
|
|
|
|
|
|
-- Test file naming: `filename.test.ts` or `filename_spec.ts`
|
|
|
-- Use descriptive test names that explain the scenario
|
|
|
-- Follow AAA pattern: Arrange, Act, Assert
|
|
|
-- Mock external dependencies
|
|
|
-- Test both success and error paths
|
|
|
-- Aim for meaningful coverage, not just high percentage
|
|
|
+1. **Read first** — Always check existing files before editing
|
|
|
+2. **Understand domain** — Review requirement materials before implementing
|
|
|
+3. **Follow conventions** — Match whatever pattern the added project uses
|
|
|
+4. **Test changes** — Run appropriate tests when available
|
|
|
+5. **Commit responsibly** — Atomic, focused commits with clear messages
|
|
|
|
|
|
## Git Conventions
|
|
|
|
|
|
-- Write clear, concise commit messages
|
|
|
-- Use feature branches for new work
|
|
|
-- Keep commits atomic and focused
|
|
|
-- Run linters before committing
|
|
|
+- Feature branches for new work
|
|
|
+- Atomic commits with clear messages
|
|
|
+- Run linters before committing (once configured)
|
|
|
- Review changes before pushing
|
|
|
|
|
|
-## Documentation
|
|
|
-
|
|
|
-- Update README.md for user-facing changes
|
|
|
-- Add code comments for complex logic
|
|
|
-- Document public APIs with docstrings/type hints
|
|
|
-- Keep documentation close to the code it describes
|
|
|
-
|
|
|
-## Cursor Rules
|
|
|
-
|
|
|
-No Cursor rules found in this repository.
|
|
|
-
|
|
|
-## Copilot Instructions
|
|
|
-
|
|
|
-No Copilot instructions found in this repository.
|
|
|
-
|
|
|
-## Working with This Repository
|
|
|
-
|
|
|
-When working in this repository:
|
|
|
-
|
|
|
-1. **Check existing structure** - Look at existing files and directories to understand the project layout before making changes
|
|
|
-2. **Understand the domain** - Read README.md and any existing documentation
|
|
|
-3. **Follow code style** - Match the existing code style in the project
|
|
|
-4. **Test changes** - Run appropriate tests when available
|
|
|
-5. **Commit responsibly** - Make meaningful commits with clear messages
|
|
|
-
|
|
|
-## Common Tasks
|
|
|
-
|
|
|
-### Running Development Server
|
|
|
-```bash
|
|
|
-# Check for available scripts
|
|
|
-cat package.json # for Node projects
|
|
|
-cat Makefile # for generic projects
|
|
|
-```
|
|
|
-
|
|
|
-### Adding Dependencies
|
|
|
-```bash
|
|
|
-npm install <package> # Node projects
|
|
|
-pip install <package> # Python projects
|
|
|
-cargo add <package> # Rust projects
|
|
|
-```
|
|
|
-
|
|
|
-### Running Tests
|
|
|
-```bash
|
|
|
-# Identify test framework first
|
|
|
-npm test # Node/Jest
|
|
|
-pytest # Python
|
|
|
-cargo test # Rust
|
|
|
-```
|
|
|
-
|
|
|
-## Best Practices for AI Agents
|
|
|
-
|
|
|
-1. **Read first** - Always read existing files before editing
|
|
|
-2. **Verify changes** - Check that changes work as expected
|
|
|
-3. **Handle errors gracefully** - Provide meaningful error messages
|
|
|
-4. **Ask for clarification** - When requirements are unclear, ask the user
|
|
|
-5. **Be proactive** - Suggest improvements when obvious issues are found
|
|
|
-6. **Respect user intent** - Don't make changes beyond what was asked unless clearly beneficial
|
|
|
-
|
|
|
-## File Organization
|
|
|
-
|
|
|
-- Keep related files together
|
|
|
-- Use clear, descriptive file names
|
|
|
-- Follow framework conventions (e.g., components in /components, tests in /tests)
|
|
|
-- Maintain consistent directory structure across the project
|
|
|
-
|
|
|
-## Performance Considerations
|
|
|
-
|
|
|
-- Avoid unnecessary re-renders or computations
|
|
|
-- Use appropriate data structures for the task
|
|
|
-- Consider lazy loading for large modules
|
|
|
-- Optimize database queries and API calls
|
|
|
-- Profile before optimizing
|
|
|
-
|
|
|
-## Security Guidelines
|
|
|
+## Security
|
|
|
|
|
|
- Never commit secrets, API keys, or credentials
|
|
|
-- Use environment variables for sensitive configuration
|
|
|
+- Use environment variables for sensitive config
|
|
|
- Validate and sanitize all user inputs
|
|
|
-- Follow OWASP security practices
|
|
|
-- Keep dependencies updated for security patches
|
|
|
+
|
|
|
+## Cursor / Copilot Rules
|
|
|
+
|
|
|
+No Cursor rules (`.cursorrules`, `.cursor/rules/`) or Copilot instructions (`.github/copilot-instructions.md`) found.
|
