A domain-organized technical knowledge base for a Rails codebase, built from the code by Claude Code, for engineers working with Claude (and the team). It documents how the project actually works — logic, data, flows, risks, reusable pieces — so you (and Claude) can answer questions, edit safely, onboard, assess impact, find danger zones, and suggest improvements.
How it runs: this kit is driven by Claude Code, not by shell scripts. The files in
meta/are instructions you point Claude at — you tell Claude in plain language to "followtech-doc/meta/setup.md", and Claude does the work (reads code, asks you questions, writes the docs). Nothing here is executed directly.
- Claude Code installed and run from inside (or next to) your Rails repo.
- Your app is a git repo (the KB stores the commit SHA it was verified against, in
synced_at, to drive updates).
Put tech-doc/ next to your app repo (as a sibling), then symlink CLAUDE.md into the
app root so Claude reads the method automatically in app sessions:
my-workspace/
├── my-app/ ← your Rails repo
│ └── CLAUDE.md → ../tech-doc/CLAUDE.md (symlink)
└── tech-doc/ ← this kit (lives here, beside the app)
# from inside your app repo (my-app/):
ln -s ../tech-doc/CLAUDE.md CLAUDE.md(If your app already has a CLAUDE.md, keep yours and instead add a line that points Claude
to ../tech-doc/CLAUDE.md.)
Give Claude write access to
tech-doc/. Because it lives outside your app repo, a Claude Code session started inside the app can't write there by default. Either run/add-dir ../tech-doconce at the start of the session, or launch Claude Code from the parent workspace folder (my-workspace/) so both the app andtech-doc/are in scope.
1. Profile the project & build the skeleton — once:
"Follow
tech-doc/meta/setup.mdfor this repo."
Claude detects the stack, proposes the business modules (it will ask you to confirm
them), fills the Project Profile in CLAUDE.md, and creates the empty
modules/ / shared/ / insights/ skeleton.
2. Document a module — repeat per module, highest-risk first (money, tenancy, auth):
"Follow
tech-doc/meta/onboarding.mdfor the<module>module."
Claude reads every method of the module's units, writes verified entries (each with
metadata + confidence + synced_at), and reconciles any existing docs at the end.
3. Keep it current — after code changes:
"Follow
tech-doc/meta/update.md." (add--fullfor a whole-codebase re-scan)
Claude diffs from the stored synced_at SHA and updates only the affected entries.
A tech-doc/ you (and Claude) read to navigate, debug, assess impact, onboard, and refactor —
always confirmed against the real code. Start from map.md and drill down.
| Part | Files | Portable? |
|---|---|---|
| Kit (the method — copy into any Rails project) | CLAUDE.md · meta/ · meta/templates/ · .vectorignore |
✅ |
| Content (generated for this project by the steps above) | map.md · architecture.md · glossary.md · modules/ · shared/ · insights/ |
❌ |
After install you only see the kit files.
modules/,shared/, andinsights/appear once you run step 1 (setup) — that's expected.
tech-doc/
├── CLAUDE.md # the method + Project Profile (filled by setup)
├── map.md # entry point: navigation + sync-state (synced_at) + coverage
├── architecture.md # stack, layers, request/job lifecycle, value chain
├── glossary.md # business term → code
├── meta/ # how to build & maintain (setup · onboarding · update + rules + templates)
├── modules/ # business areas — one dir per domain (generated)
├── shared/ # cross-cutting Rails layers, flat (generated)
└── insights/ # danger-zones · performance · improvements · reuse · gotchas (generated)
Organize by business module, not technical type; technical layers live in shared/. One
file per editable unit (model/concept), understood to the method level. Code is the
source of truth — verify against it, never guess; ask the human on business / tenancy /
security calls. Every file carries metadata (incl. confidence + synced_at). Single
source + links, no duplication. Full rules: CLAUDE.md.