62e4e50c67Improve 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-practices https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf https://agents.md/#examples
Symbolic link
1 line
No EOL
9 B
Markdown
Symbolic link
1 line
No EOL
9 B
Markdown
AGENTS.md |