Agents-First Architecture

Why .agents/ exists and how it's different from CLAUDE.md or .cursorrules.

The problem

Every AI coding agent has its own config format. Claude Code reads CLAUDE.md. Cursor reads .cursorrules. Copilot reads .github/copilot-instructions.md. Gemini reads GEMINI.md.

This creates three problems:

1. Duplication. You maintain the same project knowledge in 3-4 different files.
2. Drift. Files go out of sync. One agent gets the updated convention, others don't.
3. No memory. Agent sessions start from scratch every time. Everything learned in session 1 is gone in session 2.

The solution

.agents/ is a single structured directory that is the source of truth for all agents. Platform-specific files (CLAUDE.md, .cursorrules, etc.) are generated from it via agents sync.

Design principles

1. Knowledge belongs to the project, not the tool

When you switch from Cursor to Claude Code, your project knowledge comes with you. When a new team member opens the project in any agent, they get the same intelligence.

2. Knowledge grows automatically

Hooks capture knowledge from sessions without agent overhead. The agent doesn't spend tool calls on capture — it just works. At session end, the diff is analyzed and valuable items are extracted.

3. Structured, not freeform

Knowledge isn't a dump of notes. It's typed (architecture, pattern, lesson, convention, dependency), schema-validated, ref-checked, and freshness-tracked. agents validate catches broken refs, stale entries, and schema violations.

4. Loading policy, not context stuffing

Not all knowledge is relevant to every task. The entrypoints include a loading policy:

• For debugging, incidents, deployment — load knowledge early
• For local implementation with clear patterns — start from code, use knowledge only when needed
• If knowledge conflicts with the current task — surface the conflict explicitly

This prevents context overload while ensuring agents have what they need.

5. Human review loop

Auto-captured items land in pending/, not directly in knowledge. You review, accept, or reject. The system suggests — you decide.

What .agents/ replaces