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
# Add DSL builder tests for Request, Capabilities, and Content types
- Introduced unit tests for `RequestDslTest`, `CapabilitiesDslTest`, and
`ContentDslTest` to validate DSL builder functionality.
- Covered edge cases, nested properties, custom fields, and overwrite
behavior for requests, capabilities, and content creation.
- Update AGENTS.md
## Motivation and Context
for confidence
## Breaking Changes
No
## Types of changes
- [x] Tests
## Checklist
<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->
- [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
- [ ] I have added or updated documentation as needed
# 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)
<!-- Provide a brief summary of your changes -->
## Motivation and Context
<!-- Why is this change needed? What problem does it solve? -->
The dsl builders in [this
commit](74c93745cd (diff-598edaa01d))
were mistakenly marked internal and are therefore unusable. I have
simply marked them as public.
## How Has This Been Tested?
<!-- Have you tested this in a real application? Which scenarios were
tested? -->
## Breaking Changes
No
## Types of changes
<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->
- [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)
- [ ] Documentation update
## Checklist
<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->
- [ ] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
- [ ] My code follows the repository's style guidelines
- [x] New and existing tests pass locally
- [ ] I have added appropriate error handling
- [ ] I have added or updated documentation as needed
## Additional context
<!-- Add any other context, implementation notes, or design decisions
-->
---------
Co-authored-by: Konstantin Pavlov <1517853+kpavlov@users.noreply.github.com>
Introduce `AGENTS.md` documenting repository layout, build/test
commands, API compatibility checks, code conventions, logging/error
handling guidance, and the PR/review checklist for the Kotlin MCP SDK.
