Skip to content

docs: collect the silent-failure rules into one section - #144

Merged
prorochestvo merged 1 commit into
alphafrom
docs/restructure-claude-md
Aug 24, 2026
Merged

docs: collect the silent-failure rules into one section#144
prorochestvo merged 1 commit into
alphafrom
docs/restructure-claude-md

Conversation

@prorochestvo

Copy link
Copy Markdown
Owner

CLAUDE.md states its own job in its second paragraph: the map, plus the rules whose
violation is silent. The second kind was scattered across Architecture Overview,
Key Patterns, HTTP surface, Database, Deployment and Error Handling — a sentence or
two at a time, mixed in with material that announces itself perfectly well. Someone wanting
to know what fails quietly had to read the whole file and judge every paragraph.

They now sit under one ## Tripwires heading, grouped by the skill that carries their
reasoning:

  • Collection — egress direct by default, never widen daily, the shared-URL batching.
  • Storage — the Transaction / ReadOnlyTransaction split, tiering, weather_forecast_days
    versus the 48 h sweep, the two columns that look droppable, the cascade, the schema gate.
  • HTTP — the inner-mux bypass, header-only initData, 404-never-403, and the three
    assertions a controller error test owes.
  • Startup ordering, and there is no staging.

Everything that does report itself moved to ## Architecture (the binary map, the layer
table, routes, the health endpoints, the SQLite engine line) or ## Configuration (env vars,
deployment layout).

This is the shape #140 proposed. Its own version could not be rebased through the day's
merges, so the structure is re-derived here over current content — which #140's was missing
entirely, having branched before the outlook work.

Nothing dropped

Text is moved rather than rewritten wherever it survives, so most of the diff reads as
relocation.

backticked spans in the previous file: 191   still present: 190
figures:                                15   still present:  15

The single casualty, named rather than waved off: the spelling `/api/v1/me/...`,
normalised to `/api/v1/me/*` — the form the file already used in the other four places
it appears.

Also fixed on the way through: two code spans (`make init`, `make deploy-configs`)
were broken across a newline by the previous pass's rewrapping. A check that no span crosses a
newline now returns zero.

17823 → 17234. The saving is incidental — the file was already 2177 under budget, and the
point of this change is that the tripwires are findable, not that they are shorter.

scripts/lint-checks.sh clean. Docs only.

Refs #140

CLAUDE.md exists for two things — the map, and the rules whose violation
is silent — but the second kind was scattered through Architecture
Overview, Key Patterns, HTTP surface, Database, Deployment and Error
Handling, each a sentence or two among material that does announce
itself. A reader wanting to know what fails quietly had to read the
whole file and judge every paragraph.

They now sit under one Tripwires heading, grouped by the skill that
carries their reasoning: collection, storage, HTTP, startup ordering,
release. Everything that does report itself moves to Architecture or
Configuration. This is the shape PR #140 proposed; its own version could
not be rebased through the day's merges, so the structure is re-derived
here over current content.

Text is moved rather than rewritten wherever it survives, so the diff
reads as relocation. 17823 to 17234 — the saving is incidental; the file
was already under budget and the point is that the tripwires are now
findable.

Nothing was dropped. Of 191 backticked spans in the previous file, 190
still appear in CLAUDE.md or a skill; the one casualty is the spelling
`/api/v1/me/...`, normalised to `/api/v1/me/*`, which the file already
used everywhere else. All 15 figures survive. No code span crosses a
newline, which two of them did before this pass.

Refs: #140

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U6jNuzK5PZrhDWBxB3t2gY
@prorochestvo
prorochestvo merged commit ecbe753 into alpha Aug 24, 2026
1 check passed
@prorochestvo
prorochestvo deleted the docs/restructure-claude-md branch August 30, 2026 16:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant