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.
- .cursorrules — the same job for Cursor, phrased as editing rules: what's generated, what's authoritative, how to write diffs.
- gemini/chatgpt instruction variants — copies shaped for upload-based tools that can't read the tree live.
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.