AGENTS.md for Enterprise Projects

A single onboarding document that every AI coding agent reads first — regardless of tool

🎯 What is AGENTS.md?

AGENTS.md is an emerging cross-tool convention: a Markdown file at your repo root that gives any AI coding agent (Claude Code, Codex, Cursor, and others) the context a new engineer would need on day one — tech stack, build/run commands, architecture, and project-specific conventions.

Unlike CLAUDE.md (which is Claude Code specific), AGENTS.md is tool-agnostic. Many teams maintain AGENTS.md as the source of truth and either symlink it or keep a thin CLAUDE.md that points to it, so the same content serves every AI tool the team uses.

💡 AGENTS.md vs. CLAUDE.md vs. skills/rules

• AGENTS.md — universal onboarding doc, works with any AI tool, high-level and stable
• CLAUDE.md — Claude Code's entry point; can simply say "see AGENTS.md" plus any Claude-specific notes
• .claude/rules/ and .claude/skills/ — the detailed, path-scoped or on-demand content that AGENTS.md deliberately does not repeat (see .claude Configuration Layers and Claude Skills)

🧩 What belongs in AGENTS.md (and what doesn't)

A well-scoped AGENTS.md stays short and structural. Detailed, repetitive conventions (naming style, per-layer coding rules) belong in skills/rules instead — otherwise the file balloons and stops being read carefully.

Include	Push to skills/rules instead
Tech stack and versions	Full language style guide
Build / run / test commands	Every possible test scenario
Startup order for multi-service projects	Detailed API documentation
High-level architecture and module map	Per-layer (controller/service/mapper) code templates
Project-specific "gotcha" conventions (e.g. a custom response wrapper)	Generic best practices already covered by a skill

📖 Example structure (multi-module backend project)

# AGENTS.md

This is the unified development guide for the Cloud Platform project.

> Generic coding conventions (naming, formatting, OOP, exceptions, logging,
> security, database, testing) are provided by skills — see `.claude/skills/`.
> Layer-specific rules (controller, service, mapper, entity, dto) are
> auto-loaded by file path — see `.claude/rules/`.

## 1. Tech Stack
- Java 17, Spring Boot 3.5.5, Spring Cloud 2025.0.0
- MyBatis Plus, Undertow, Druid
- pom.xml is the source of truth for versions if this doc drifts

## 2. Build & Run
​```bash
mvn clean install -DskipTests
mvn test -pl module-name -Dtest=SomeTest
​```

## 3. Startup Order
1. registry-service (service discovery) [8848]
2. core-biz-service (wait for route init) [4000]
3. auth-service [3000]
4. gateway-service [9999]

## 4. Architecture Overview
Multi-module Spring Cloud microservices platform, two deployment modes:
- `cloud` (default): full microservices with service discovery
- `boot`: monolith mode via a bundled aggregator module

| Module | Responsibility | Port |
|---|---|---|
| registry-service | Service discovery & config center | 8848 |
| gateway-service | Unified entry point | 9999 |
| auth-service | OAuth2 authorization server | 3000 |

## 5. Project-Specific Conventions
- Constructor injection only (`@RequiredArgsConstructor`); `@Autowired` is banned
- All responses wrapped in `R<T>`: `R.ok(data)` / `R.failed(msg)`
- Enum fields must use the project's `@EnumValue` validator annotation

## 6. Code Examples
​```java
@RestController
@RequiredArgsConstructor
@RequestMapping("/example")
public class ExampleController {
    private final ExampleService exampleService;
}
​```

💡 Keep the "source of truth" note

Notice the line "pom.xml is the source of truth for versions." Docs drift; build files don't lie. Calling out which file wins when they disagree saves the AI (and new hires) from acting on stale info.

🚀 Writing AGENTS.md for your project

1. Start with what a new hire needs on day one — stack, how to build/run, how to run one test, startup order for multi-service setups
2. Add an architecture map — module table with responsibility and port/entry point, not full API docs
3. List the 3-5 conventions that are easy to get wrong — the ones that aren't obvious from reading code once (e.g. "don't use @Autowired", "all DTOs need @Size matching the DB column length")
4. Point to skills/rules for depth instead of inlining everything — keep AGENTS.md skimmable
5. Add 1-2 minimal code examples per architectural layer so the AI matches your actual style, not a generic framework default
6. Keep it in sync — treat AGENTS.md like code; update it in the same PR that changes a build command or startup order

⚠️ Common mistake: AGENTS.md as a dumping ground

Teams often start disciplined and then paste in more and more detail over time until the file is thousands of lines and nobody — human or AI — reads all of it carefully. If a section only applies to one file type or one scenario, it almost always belongs in .claude/rules/ (path-scoped) or .claude/skills/ (on-demand) instead.

🎉 Result

A well-written AGENTS.md means any teammate — or any AI tool — can clone the repo and be immediately productive: they know the stack, how to build it, how services start up, and the handful of conventions that would otherwise take a code review comment to catch.