🌿 Make any project agent-ready

“Agent-ready” means the repo carries its own context: any developer — or AI coding agent — can land in it and be productive without a senior explaining the architecture for the tenth time. The context lives in committed files, so it holds across the team and outlasts whoever wrote it.

The why: Onboarding a human and onboarding an AI are the same problem.

Rule zero: explore before you write

Read the codebase first — stack, directory structure, architecture patterns, conventions, key files, how it all connects. Every file below must be tailored to the actual project, not a generic template. A generic CLAUDE.md is worse than none: it teaches the agent wrong things, confidently.

1. Agent context files

File	Read by	Contents
CLAUDE.md	Claude Code, Gemini CLI	Project identity, stack table, directory map, architecture patterns, critical DO-NOT warnings, conventions, common commands, key files to read first
.cursorrules	Cursor	DO / DO-NOT lists, file naming, code style, architecture quick-ref, commands
.windsurfrules	Windsurf / Codeium	Same content as .cursorrules
.github/copilot-instructions.md	GitHub Copilot	A concise version of the above

The highest-value section in any of these is the “DO NOT” list — the project-specific traps (don’t mutate that global, don’t call that API in a loop, don’t hand-edit generated files). That’s the knowledge that otherwise only lives in scar tissue.

2. Architecture docs

• ARCHITECTURE.md — system overview, module/component architecture, data flow, API layer, state management, external integrations. Use Mermaid diagrams; humans and agents both parse them.
• docs/adr/ — Architecture Decision Records for the handful of decisions that shaped the project (framework, build system, state management, API pattern, deployment). Include 000-template.md and a README.md index. Each ADR carries: Status, Date, Context, Decision, Consequences (positive / negative / risks). ADRs answer the question new hires and agents ask most: why is it like this?

3. Developer workflows (.agent/workflows/)

One short file per task so nobody reverse-engineers the process: setup.md, docker.md, test.md, deploy.md. Concrete commands, not prose.

4. Standards

• CONTRIBUTING.md — branch naming, commit format, code standards, a new-file checklist, the PR process.
• .github/CODEOWNERS — map paths to owners so reviews route themselves.
• .github/PULL_REQUEST_TEMPLATE.md — a checklist with project-specific items.

5. Housekeeping

• .editorconfig — indent, charset, line endings, so formatting stops being noise in diffs.
• .gitignore — add agent state dirs: .gemini/ .claude/ .cursor/ .aider* .copilot/ .windsurf/ .vscode/ .env*.
• README.md — the front door; link out to everything above.

The rules that keep it honest

• Zero runtime code changes — docs and config only.
• Tailor everything to the real project — explore first; no boilerplate.
• Write the DO-NOT warnings — the traps specific to this codebase.
• Commit it all to git — context that isn’t committed doesn’t sync, and syncing across developers is the entire point.

Checklist

• Explored stack, structure, patterns, conventions, key files
• CLAUDE.md + .cursorrules + .windsurfrules + copilot instructions, tailored
• ARCHITECTURE.md with diagrams
• docs/adr/ with template, index, and the top decisions
• .agent/workflows/ for setup / docker / test / deploy
• CONTRIBUTING.md, CODEOWNERS, PR template
• .editorconfig, .gitignore agent dirs, project README.md
• Everything committed

Related

• Onboarding a human and onboarding an AI are the same problem