AgentRules

English · 简体中文

A practical workflow for reliable AI-assisted software development.

AgentRules is a reusable workflow for AI-assisted software development. It guides coding agents from understanding a request through implementation and verification, with an emphasis on clarity, simplicity, architectural integrity, focused changes, and observable results.

It can be used with Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI, and other coding agents through their global or project instruction mechanisms.

Why AgentRules

AI coding agents can write code quickly, but speed alone does not make a change correct or maintainable. Common failure modes include silently guessing requirements, adding unnecessary abstractions, bypassing an existing framework, touching unrelated code, and claiming success without verification.

AgentRules turns those risks into an explicit working process. It asks the agent to define success before coding, make the smallest suitable change, preserve the project's architecture, and verify the result through normal project entry points.

The Workflow

1. Clarify the outcome: turn the request into concrete acceptance criteria and state assumptions.
2. Choose the simplest solution: avoid speculative features, abstractions, and configuration.
3. Respect the existing system: inspect the architecture and extend it through established boundaries.
4. Change only what is needed: keep the diff focused and avoid unrelated cleanup.
5. Work toward verifiable goals: reproduce bugs, add focused tests, and check the final behavior.
6. Keep failures diagnosable: preserve useful error context without noisy or sensitive logs.
7. Finish the requested product surface: cover relevant validation, loading, empty, error, accessibility, and responsive states.
8. Verify external integrations: use current primary documentation instead of guessing APIs or SDK behavior.
9. Use sub-agents deliberately: delegate only when parallel work provides clear value.

Expected Effects

Following the workflow helps teams get:

• Fewer misunderstandings caused by hidden assumptions
• Smaller, easier-to-review diffs
• Less overengineering and speculative code
• Better preservation of framework and architecture guarantees
• Clearer tests and completion criteria
• More diagnosable failures without leaking sensitive data
• More reliable third-party integrations
• More focused use of agent time and context

These guidelines do not replace engineering judgment. They make that judgment visible, reviewable, and easier to apply consistently.

Use AgentRules

Clone the repository and review AGENTS.md:

git clone https://github.com/LearnAIHubC/AgentRules.git

Then add the file or its contents to the global or project instruction mechanism supported by your coding agent. Tools that read AGENTS.md can use it directly. For other tools, copy or reference the content from their supported instruction file or settings.

Keep the shared rules as a baseline and add project-specific guidance where needed. Review model-specific preferences before adoption and adjust them to the models available in your environment.

Contents

AgentRules/
|-- AGENTS.md
|-- README.md
|-- README.zh-CN.md
`-- LICENSE

Contributing

Issues and pull requests are welcome. Keep proposed rules concrete, broadly useful, and tied to a verifiable improvement in agent behavior.

License

MIT License. See LICENSE.