Recommended Global Rules for AI Assistants
To ensure AI coding agents (such as Claude Code, Codex, Cursor, etc.) modify your code safely and follow best practices, we recommend placing a rule file named AGENTS.md or CLAUDE.md at the root of your project directory.
AI agents will automatically scan for these files and adapt their behavior accordingly.
1. Design Concept: Progressive Spec
Before performing any large-scale changes, the agent should structure the requirements:
- Small tasks (e.g., fixing a bug, updating a field): Can be executed directly with immediate verification.
- Medium tasks (e.g., refactoring a component): The agent should outline a brief plan first.
- Large tasks (e.g., adding a new module): The agent must write a complete specifications plan, get confirmation, and proceed step-by-step.
2. Rule Template Full Text
Copy the template below and save it as AGENTS.md or CLAUDE.md in the root of your repository:
markdown
# AI Coding Guidelines
## Working Principles
- **Read before writing**: Always read the relevant source files and project structure before proposing modifications.
- **Minimize diff footprint**: Focus modifications strictly on the requested task. Do not perform unrelated refactoring or formatting sweeps.
- **Do not overwrite manual changes**: If the user has made changes, respect and integrate them.
- **Explain risks**: For high-risk operations (e.g., updating database schemas or critical dependencies), explain the potential side effects first.
## TopRouter Configuration Boundaries
- All TopRouter API connections must use the base URL: `https://toprouter.cc` (never append `/v1`).
- Secure your API keys: Never commit raw API keys to code repositories, configurations, or logs. Use environment variables.
## Testing and Verification
- Run tests: Propose and run test suites locally whenever possible to verify changes.
- Layout check: When editing user interfaces, verify rendering across both desktop and mobile viewports.
- Explain failures: If a task cannot be verified locally, explicitly explain the reason and state any residual risks.