Instruction files (tool-facing)
These are read automatically by tools:
- claude.md — project instructions for Claude Code: the folder map, conventions, and standing rules. Loaded at session start.
- AGENTS.md — the same job in an open format most agents read, Cursor included: what's generated, what's authoritative, how to write diffs. Cursor can add glob-scoped rules on top in .cursor/rules/; the older .cursorrules is legacy.
Working files (human-facing)
These structure the actual work:
- Workflow.md — a repeatable checklist for the workspace's core loop (weekly update, revision cycle, client delivery).
- README.md inside folders — one paragraph on what belongs here and what good looks like. The single highest-leverage file to customise.
- Templates (*-template.md) — duplicate, fill in, never edit the original.
The rule of one source
When two files could hold the same fact, the instruction files point to the working file rather than duplicating it. claude.md says where the roadmap lives; it never contains the roadmap. That's what keeps a workspace maintainable at 100+ files.