docs: update AGENTS.md

[devcrocod]

Improve AGENTS.md

Motivation and Context

The previous AGENTS.md contained many elements contradicting 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 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

• 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

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• 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

[Copilot]

Pull request overview

This PR streamlines the always-loaded AI agent guidance by replacing the previous long, highly prescriptive AGENTS.md with a shorter, general-purpose set of repository notes and common commands, and aligns CLAUDE.md accordingly.

Changes:

• Condenses AGENTS.md from a large rule set into a short “project/build/structure/conventions/testing/skills” guide.
• Updates CLAUDE.md to reflect the new guidance source/content.
• Adds focused build/test/conformance command snippets intended for quick agent/operator use.

Reviewed changes

Copilot reviewed 2 out of 3 changed files in this pull request and generated 2 comments.

File	Description
CLAUDE.md	Updated AI context guidance file; currently duplicates AGENTS.md content.
AGENTS.md	Rewritten to be concise and general-purpose, with build/test/conformance pointers and key conventions.

Comments suppressed due to low confidence (1)

CLAUDE.md:3

• CLAUDE.md currently duplicates the entire contents of AGENTS.md verbatim. This creates two sources of truth to keep in sync; consider making CLAUDE.md include/reference AGENTS.md (or otherwise avoid duplication) so future edits only need to happen in one place.

# AGENTS: Development Guidelines for AI Contributors

This file provides guidance to AI coding agents working with code in this repository.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

[kpavlov]

I agree, that project information was a bit redundant. Everything else is a degradation.
These instructions are now useless and will negatively affect code quality. Let's revert requirements, they are useful and should be loaded on every conversion.

[devcrocod]

@kpavlov
I included a number of arguments in the PR description, have you had a chance to review them?
I did not go through every single line of the previous agents.md, because that would have taken even more time. However, I can justify every removal by referring to the relevant recommendations.

Could you please explain in more detail why you are blocking this PR?