Improve AGENTS.md
## Motivation and Context
The previous AGENTS.md contained many elements contradicting [best
practices](https://code.claude.com/docs/en/best-practices).
AGENTS.md/CLAUDE.md is loaded into the context on every request, so a
~300+ line file is too large and fills the context window.
> Keep it concise. For each line, ask: “Would removing this cause Claude
to make mistakes?” If not, cut it. Bloated CLAUDE.md files cause Claude
to ignore your actual instructions!
> Most best practices are based on one constraint: Claude’s context
window fills up fast, and performance degrades as it fills.
> The over-specified CLAUDE.md. If your CLAUDE.md is too long, Claude
ignores half of it because important rules get lost in the noise.
Since the file is loaded on every request, it should be general-purpose
rather than targeting specific use cases.
> CLAUDE.md is loaded every session, so only include things that apply
broadly.
AI coding agents are used not only for writing tests and
implementations.
- AGENTS.md should not contain behavioral instructions, especially like
`Tests first, always.`. This causes the agent to trigger test runs even
when not required, increasing request time and token consumption
significantly due to large test outputs. For example, on a simple
codebase question, the agent ran the full test suite and I waited over
10 minutes for a response.
- `Uphold SOLID principles` — self-evident rules, explaining what SOLID
stands for is redundant since AI coding agents are already trained on
this knowledge.
> Exclude: "Standard language conventions Claude already knows"
> Exclude: "Self-evident practices like 'write clean code'"
- Mentioning specific MCP servers (jetbrains, intellij-index) can
mislead the agent if they are not installed in the environment.
Additionally, [Anthropic
recommends](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf)
mentioning the use of MCP in skills.
- The large Kotest patterns block targets a specific use case and is
unnecessary for other agent interactions. Moreover, the agent already
looks at neighboring test classes and can learn patterns from existing
tests
- The large Module documentation block covers a very rare use case.
- The KDoc block — the agent can derive this information from the
codebase, this should be a skill instead
These and other changes follow the best practices.
## Types of changes
- [x] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
## Checklist
- [x] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
- [x] My code follows the repository's style guidelines
- [x] New and existing tests pass locally
- [x] I have added appropriate error handling
- [x] I have added or updated documentation as needed
## Additional context
https://code.claude.com/docs/en/best-practiceshttps://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdfhttps://agents.md/#examples
# docs: Update AGENTS.md
- Introduce CLAUDE.md symlink to AGENTS.md
- Enhance AGENTS.md with updated test setup, coding standards, and
module-specific practices
## Motivation and Context
Motivation: Improve consistency, readability, and maintainability of
code contributions across AI agents and developers.
## Breaking Changes
No
## Types of changes
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
## Checklist
- [x] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
- [x] My code follows the repository's style guidelines
- [x] New and existing tests pass locally
- [ ] I have added appropriate error handling
- [x] I have added or updated documentation as needed
## Verified
<img width="584" height="225" alt="image"
src="https://github.com/user-attachments/assets/591202a3-56aa-4901-ad5d-9e2d4b9f0013"
/>
(I have other files locally, but AGENTS.md is known to Claude)
