Agent repo layout
The repo-level source of truth, compatibility symlinks, local-state directories, and gitignore rules for Claude Code, Codex, Cursor, and other agents.
This repo keeps agent configuration intentionally boring: one readable source of truth, a small compatibility layer for tools that still look for their own files, and ignored directories for local agent state.
Source of truth
AGENTS.md
is the repo-level SSOT for runtime instructions. It is the first file to check
when an agent needs branch workflow, validation gates, cloud-dev constraints,
merge behavior, or multi-agent directory rules.
CLAUDE.md is a symlink to AGENTS.md. Keep edits in AGENTS.md; do not
replace the symlink with a second copy of the same guidance.
Versioned agent assets
Use .agents/ for agent-owned files that belong in the repo:
| Path | Purpose |
|---|---|
.agents/skills/ | Versioned SKILL.md runbooks loaded on demand by compatible agent tools |
.claude/skills is a compatibility symlink to .agents/skills. This lets
Claude Code continue to find the same skills while keeping .agents/ as the
tool-neutral home.
Local-only agent state
Use ignored paths for generated state, logs, notes, temp files, and worktrees:
| Path | Purpose |
|---|---|
.agents/logs/ | Per-iteration agent logs |
.agents/notes/ | Scratch notes and investigation leftovers |
.agents/reports/ | Generated local reports |
.agents/tmp/ | Temporary files that should never be reviewed |
.agents/worktrees/ | Optional local Git worktrees for parallel agents |
.claude/worktrees/ | Legacy / tool-specific local worktree state |
.worktrees/ | Legacy local worktree state |
Do not commit files under these paths. If a note becomes durable project
knowledge, move it into this docs site or into AGENTS.md, depending on
whether humans or runtime agents need it first.
Cursor files
Cursor can read a root AGENTS.md for simple project instructions. Commit
only .cursor/rules/*.mdc files for scoped Cursor-specific rules that need
metadata or file-pattern attachment. Use .cursor/environment.json for
Background Agent machine setup when the repo needs repeatable remote setup.
Do not add .cursorrules; Cursor keeps it for legacy compatibility, but the
current project-rule path is .cursor/rules/.
When to update what
| Change | Update |
|---|---|
| Runtime rule every agent must obey | AGENTS.md |
| Expanded human-readable explanation | This docs site |
| Repeatable external-service runbook | .agents/skills/<name>/SKILL.md |
| Cursor-only scoped behavior | .cursor/rules/<name>.mdc |
| Local generated output, investigation notes, temp files | Ignored .agents/* path |
Keep this page and AGENTS.md aligned. AGENTS.md is optimized for prompt
loading; this page is optimized for navigation and review.
Related
- Agent skills — what lives in
.agents/skills/ - Parallel worktrees — how to create and
remove
.agents/worktrees/<name>/ - Reading paths — where agents should start
MSW mocks
MSW (Mock Service Worker) is the architectural mock layer — Storybook stories, unit tests, and the runtime `mockMode=true` path all share the same handlers and fixtures.
Cloud dev (Claude Code on the web)
Running this repo end-to-end inside Claude Code on the web — credential flows, env panel, network allowlist, MCP servers.