The Problem I’m a solo dev on a multi-tenant SaaS platform — 135 database tables, 80+ pages, 60+ API route files, 15 production customers. Claude Code forgets everything between sessions. Every time I start a new task, it guesses at file names, table names, and route paths — and gets them wrong. Real examples of what went wrong: - It edited a 41KB dead code file instead of the active one (same feature, different filename) - It referenced device_readings in queries — that table doesn’t exist, the actual table is vital_signs
- It assumed column names without checking the schema and wrote broken SQL Each of these cost me 15-30 minutes to debug. On a production healthcare platform, that’s not just annoying — it’s dangerous. The Solution Two living markdown docs that Claude Code reads before every task and updates after. Self-maintaining documentation that gets more accurate over time instead of rotting. Step 1 — Generate the skeleton automatically I pointed Claude Code at my App.tsx (all frontend routes), server.js (all backend route mounts), and sidebar navigation components. One command: /hey-claude Generate a system documentation skeleton by reading all routes, components, and API endpoints. READ-ONLY investigation, output to markdown. 7 minutes later: a 2,161-line ROUTE_REFERENCE.md mapping every page to its component, backend API endpoint, database tables, and access control. Auto-generated from the actual source code, not hand-written. Each page entry looks like:
Care Team
URL:
/patient/:id/care-team
Component:
CareTeamNew.tsx
Access:
ProviderBlocked (provider role gets read-only)
Backend API:
GET /api/care-team/*
→
careTeamRoutes.js
Database tables:
care_team_members
,
providers
,
users
Known issues:
blank
Last audited:
blank
Step 2 — Consolidate with human knowledge The auto-generated skeleton had the routes right but was missing context only I know — bug history, data cleanup status, architectural quirks, security audit findings, recent changes. I merged it with my manual notes into SYSTEM_DOCS.md (the canonical doc). The skeleton becomes the detailed reference. The consolidated doc becomes the source of truth with sections like: - Identity architecture (how the auth model actually works) - Known bugs ranked by priority - Data cleanup status (what’s been fixed, what’s pending) - Recent changes log - Security audit TODOs Step 3 — Git-track both files bash git add SYSTEM_DOCS.md ROUTE_REFERENCE.md git commit -m “Add system docs and route reference” Now they deploy to both my dev and production servers automatically through the normal git flow. No manual syncing. Step 4 — Wire Claude Code to use them automatically In .claude/commands/hey-claude.md (a custom command that runs before every implementation task), I added:
PRE-IMPLEMENTATION: READ DOCS
Before writing any code: 1. Read SYSTEM_DOCS.md — find the section for the page/feature being changed 2. Read ROUTE_REFERENCE.md — find the route, component, and API endpoint 3. Note any Known Issues listed for that section
POST-IMPLEMENTATION: UPDATE DOCS
After all code changes are verified: 1. Update SYSTEM_DOCS.md — add Known Issues, update Last Audited date, add to Recent Changes Log 2. Do NOT update ROUTE_REFERENCE.md unless routes were added or renamed ```
And in
CLAUDE.md
(the file Claude Code reads at session start):
```markdown
Documentation
System docs:
SYSTEM_DOCS.md — read before implementing, update after.
Route reference:
ROUTE_REFERENCE.md — detailed route-to-component mapping.
These are the source of truth. ```
The Result
Every task now follows this loop:
Claude Code reads the docs → knows which file to edit, which table to query, what bugs already exist
Implements the feature
Updates the docs with what changed, what's now broken, when it was last verified
The documentation gets more accurate with every session instead of going stale. And I haven't had a "wrong file" or "wrong table name" incident since setting this up.
Tips if you try this
Let Claude Code generate the skeleton
— don't hand-write it. It reads the actual source code and catches routes you forgot existed.
Keep the two docs separate
— the auto-generated route reference is big and detailed (~2,000 lines). The human-curated system doc is smaller (~600 lines) with context Claude Code can't infer from code alone.
Git-track them
— if they're not in version control, they'll drift between environments.
The "Last audited" field is key
— it tells you which sections are stale. When Claude Code updates a section after implementing a feature, it fills in the date. Sections without dates haven't been verified.
Don't let Claude Code update docs it didn't verify
— the post-implementation update should only touch sections related to the feature it just built. Otherwise it'll confidently fill in wrong information.
The whole setup took about 2 hours (mostly reviewing and consolidating the auto-generated skeleton). It's saved me way more than that in the two weeks since.
submitted by
/u/burningsmurf
Originally posted by u/burningsmurf on r/ClaudeCode