Not a token ledger — a content audit. What are the actual policies? What's just
notes? What's good to keep, and what should have been a skill or a doc all along?
of the file is actual policy — 65 lines out of 1,563.
The other 96% is reference material, architecture prose, and war stories.
That single ratio reframes the whole problem. This was never a file that's "too long" — it's
a rulebook with a library bound into it. The rules are excellent. The library
shouldn't be there.
01The four kinds of content
Everything in the file is one of these. Only the first belongs in CLAUDE.md.
Policy✓ keep~65 lines
A rule Claude must follow, phrased so a violation is checkable. These are the crown
jewels — the "each line was a bug" content. They're short, imperative, and mostly
excellent.
Example — line 1657"NEVER run npm run seed without explicit permission — it destroys
conversations and work orders."
Stays in CLAUDE.md. Short, universal, always-on.
Notes & war stories✗ move~40 lines
Incident archaeology: dates, PR numbers, what someone believed before, how long a
misdiagnosis took. Valuable history — but it's justification, not instruction.
Claude cannot act on it; it just has to read past it.
Example — the ANTHROPIC_AUTH_TOKEN row"This row previously said flatly '429 IS the weekly cap'; that sentence cost an hour
on 2026-07-16 diagnosing 5 'capped' accounts that were fine — agent-smith, which injects
the identity, was working on the same tokens the whole time."
→ an incident doc or ADR, with a one-line rule and a link left
behind. Keep the why in one clause; move the forensics.
Reference & catalogs✗ movethe bulk
Directory trees, route tables, env-var catalogs, page listings, agent IDs, tool
inventories. Claude can re-derive nearly all of it by reading the repo — and a
hand-maintained copy goes stale, which makes it worse than absent.
Example — the Project Structure section
101 lines drawing the src/ tree in ASCII. Every new directory silently
makes it more wrong.
→ docs/, behind a one-line pointer. This is
exactly the class /doctor flags for trimming.
Procedures & runbooks✗ move~12,000 tokens
Numbered, multi-step operations you follow when a specific thing happens: debugging a
stuck renewal, offboarding a staff member, repairing a Google Workspace rename. You need
them maybe monthly, and you know when.
Example — "Debugging a stuck or wrong renewal"
A five-step ladder with raw aws dynamodb commands. 115 lines that are dead
weight in every session that isn't debugging a renewal.
→ a skill. Loads on demand, costs one description line otherwise.
This is the textbook skill shape.
02The policies we actually have
Extracted and grouped. This is the real rulebook — and it would comfortably fit in
150 lines.
Truth & evidence
No fabricated numbers. Every figure traces to a real source or is marked pending.
Label inference vs fact. Verify before any causal or negative claim, or mark it a hypothesis.
Lock user corrections. Once corrected, it's truth for the session.
Values that look real must be real. Never mint a system-of-record identifier locally.
Never silently default a value AppFolio renders — missing policy fails loud.
Verify before "done" — browser, API or DB pass on real output; unit tests alone don't count.
Dangerous actions
Never npm run seed without explicit permission — destroys data.
Never next build directly — use npm run build for the mutex.
Never rm -rf .next on production — move it instead.
Never hardcode credentials — secrets live in .env.local.
Never merge or deploy without permission.⚠ contradicted elsewhere — see below
Git & shipping
Worktree + PR, always. Never edit the main repo working dir.
One concern per PR. Stage explicitly, never git add -A.
Plan before multi-file work, then wait for approval.
Run npm test after every change. Fix failures before moving on.
Every behaviour change ships a test that fails on the bug and passes on the fix.
Prompt changes run npm run test:eval before merge.
Every classification bug becomes a promptfoo eval case.
No mock theatre — never mock our own layer when that layer is the subject.
Architecture boundaries
One source of truth — no legacy paths, no parallel implementations, no shims.
Multi-tenant by construction — no client, property or customer baked into source.
Domain code must not import integrations directly — go through the PMS adapter.
Source labels stay PMS-agnostic — 'pms' | 'unavailable', never 'appfolio'.
The PMS owns identifiers — PropFlow mirrors, never mints.
Org resolution comes from the entity's anchor, never the session user.
No PII across the Temporal activity boundary.
No arms by default — a shipped feature should just work.
UI
Arsenal first — check the registry before writing a new component.
Never raw <select> → FilterDropdown.
Never generic spinners → LogoAnimation or ClaraThinking.
Never confirm()/alert()/prompt() — ESLint-banned.
Never a raw max-w-7xl page root → <PageBody>.
Phosphor icons only. No other icon library.
Plain English in customer-facing copy — no enums, acronyms or AI jargon.
No hardcoded colours — var(--color-*) tokens only.
That's the whole rulebook — around forty distinct policies. Notice how many are one line and
immediately checkable. This is what good looks like, and it's already here; it's just
buried in two thousand lines of everything else.
03Good and bad, by the official standard
Anthropic publishes an explicit list of what belongs in a CLAUDE.md. Mapped against ours:
✓ Belongs — and we have it
Commands Claude can't guess — npm run build's mutex
Conventions that differ from defaults — worktree + PR
Testing instructions and runners
Repo etiquette — branch naming, one concern per PR
Architectural decisions — one source of truth, multi-tenancy
Environment quirks — the counterfeit-429 tell
Non-obvious gotchas — elevenlabsConversationId stamped at ring, not pickup
✗ Doesn't belong — and we have it
Anything derivable from code — the src/ tree, route tables
Detailed API documentation — 72 lines of endpoints
Info that changes frequently — agent IDs, env catalogs
Long explanations — the 68-line email-rename essay
File-by-file descriptions — 101 lines of structure
Multi-step procedures — four runbooks
Duplicated content — graphify and Trello are already skills
Three things we do genuinely well
Worth naming, because the fix is to do more of these rather than invent something new:
1 — the arsenal checklist phrasing"About to write <table>? → use HoverRow,
SortableHeader…" — a trigger paired with an answer. Concrete,
verifiable, impossible to misread. The best-written thing in the file.
2 — rules backed by drift guards
Many policies name the test that enforces them
(agent-name-handler-coverage.test.ts). That's a rule that survives whether or
not Claude read the line — enforcement, not prose.
3 — six sections that are pure pointers
"The architecture lives at docs/architecture/…, read it before X." Cheap,
current, and the model for everything else.
04What's wrong right now
A real contradiction — two rules disagree on merge authority
Line 1656:"NEVER deploy or merge to main without explicit user permission…
wait for explicit approval."
Line 1725:"Merge on green… There is no separate human sign-off gate; green
is the gate."
Both canonical sections, 69 lines apart, irreconcilable for any agent-loop PR. This needs
one answer no matter what we decide about structure — and it's the clearest evidence that
volume has not been buying compliance. Found by Codex, verified against the file.
Smaller, all cheap to fix:
Defects found while auditing
Two sections duplicate live skills — graphify and
Trello automation.RETRACTED — verified before editing and they are
not duplicates. The graphify skill is the generic upstream tool doc while
CLAUDE.md carries PropFlow-specific policy (S3 sharing, the nightly Smith refresh, the
--backend claude-cli prohibition); the Trello skill covers the board API
while CLAUDE.md documents three repo shell scripts that exist in scripts/.
Acting on this as originally written would have deleted ~99 lines of real content.
Stale repo path — the Overview says the project lives at
~/.claude/propflowai/. It doesn't.
Dead absolute paths — the renewal reset runbook points at
/Users/federicochapa/…, which no session on this machine can follow.
Safety rules hidden in a catalog — the env-var table contains "don't use
the prod-lane number, it writes to propflow-prod". That's a policy wearing a
reference table's clothes, and it nearly got moved by mistake.
05What I'd do
In order, cheapest and least controversial first.
Now — uncontested
Resolve the merge-authority contradiction. Pick one answer. Costs nothing,
fixes a live ambiguity.
Delete the two duplications, leaving a pointer to each skill.
Fix the stale paths.
Move the four runbooks to skills — they're already shaped like skills.
Move the catalogs to docs/ behind pointers, carving out the
safety rules hiding inside them.
Next — worth debating
Promote the "never" rules to hooks. A PreToolUse hook enforces;
prose only requests. Independent of everything else here, and possibly the highest-value
change on the list.
Move incident forensics to ADRs, keeping one why-clause and a link.
Then reassess. What's left is close to a real policy kernel — and we'll know
whether the remaining bulk was ever the problem.
06Open questions
Q1 · needs a decision
Merge authority — approval, or green?
The two rules contradict. Which one is real, and does it differ for agent-loop PRs
versus everything else?
Q2 · needs a decision
Should the "never" rules become hooks?
Never push without asking, never run seed, never next build directly. Hooks
are guaranteed; prose competes with two thousand lines. Claude's view: yes, and
it's the single highest-leverage item here.
Q3 · open
Does our plan-first workflow break path-scoped rules?
Scoped rules load when Claude reads a file — which happens after planning.
Codex's counter: put a mandatory routing table in the always-on kernel ("if touching X,
read Y") so planning knows what to pull.
Q4 · open
Who owns this file?
It reached 2,088 lines with no pruning ritual. Options: review in PR like code, a
Stop hook proposing updates from the session transcript, or a scheduled
re-read.