Skip to content

docs(claude): move architecture depth into skills - #140

Closed
prorochestvo wants to merge 3 commits into
alphafrom
docs/slim-claude-md
Closed

docs(claude): move architecture depth into skills#140
prorochestvo wants to merge 3 commits into
alphafrom
docs/slim-claude-md

Conversation

@prorochestvo

Copy link
Copy Markdown
Owner

Slims CLAUDE.md from 21133 to 11996 bytes (-43%), under the 12k budget its own routing block sets. No new skill was created — every block found a home in one of the five that already existed.

What moved where

Block Destination
Source kind (BID/ASK/LAST), the options JSON column, cmd/doctor rulegen/audit, the Telegram proxy bypass and the dead HTTPS_PROXY/HTTP_PROXY/NO_PROXY variables beacon-collection
Connection PRAGMAs, the BEGIN IMMEDIATE / deferred-read split and the SQLITE_BUSY story, the repository pattern, foreign-key cascade and RemoveRateSource, deploy-time schema reconciliation beacon-storage
The initData HMAC scheme, --api-dsn, the PublicError contract and the three controller-error-test assertions beacon-http-api
Pipeline procedure (plan / implement / gate / review / complete, plans/ layout, the four agents) pipeline:working-agreement, via its delta form
Env var rows internal/env.go, which already declares every name, format and consumer
Deployment mechanics deploy/README.md

Each extended skill also got an extended description, so the new material has load triggers. A skill that gains content but not triggers loses it.

The beacon-http-api auth section previously read "The HMAC algorithm is in CLAUDE.md's Key Patterns" — that pointer would have dangled after this change, so the algorithm is now written out in the skill itself.

What stays in CLAUDE.md

The binary and layer map, the skills table, the routing block, ## Data & Privacy, ## Constraints, the gate, startup ordering, and a ## Tripwires section collecting every rule whose violation is silent — tiered reads, the weather_forecast_days 48 h sweep, the inner-mux auth mount, 404-not-403, r_* tags going straight to production.

Gate notes recorded

make lint and make lint-new each run two steps, golangci-lint run and scripts/lint-checks.sh — a green golangci-lint alone is not a green make lint. And on the pi5 make test dies compiling modernc.org/sqlite under -race; the rerun is go test -race -p 1.

Verification

All 227 backticked tokens were extracted from the old file. 225 appear verbatim in the new CLAUDE.md, one of the five beacon skills, pipeline:working-agreement, stack-go, or a repo file. The remaining two survive by meaning:

  • /api/v1/me/... — kept as /api/v1/me/*, the same referent in the notation used everywhere else.
  • /opt/beacon/artifacts/<VERSION_ID>/ — in deploy/README.md (layout tree plus the VERSION_ID definition) and literally in .github/workflows/release.yml.

Docs only; no code touched, so the gate is unaffected.

prorochestvo and others added 3 commits August 23, 2026 11:55
CLAUDE.md drops from 21133 to 11996 bytes, under the 12k budget its own
routing block sets. Nothing was removed outright; every subject moved to
the skill that already owned its area.

beacon-collection gains the source kind vocabulary (BID/ASK/LAST) and the
options JSON column, the unconditional Telegram Bot API proxy bypass with
the note that the standard HTTPS_PROXY/HTTP_PROXY/NO_PROXY variables are
read by nothing here, and cmd/doctor as the operator-only umbrella for
rule generation and source auditing.

beacon-storage gains the connection PRAGMAs and the two places they are
applied from, the BEGIN IMMEDIATE write / deferred read split and why it
is what makes busy_timeout reachable, the repository pattern and its
transaction helpers, the foreign keys that cascade a source deletion into
its history, and the deploy-time schema reconciliation note.

beacon-http-api gains the initData HMAC scheme, which previously pointed
back at CLAUDE.md and would have dangled, the --api-dsn public-origin
flag, and the PublicError contract with the three assertions every
controller error test owes.

Each skill description was extended alongside its body so the new
material has load triggers; content behind a description that does not
name it never loads.

The working agreement collapses to the pipeline:working-agreement delta
form, keeping the branching override in full: branch off alpha, PR
against alpha, main only tracks the latest non-prerelease tag, a merge
into alpha does not close its issue because GitHub honours the closing
keyword only on the default branch, and gh pr create needs an explicit
--base alpha. The gate records that make lint runs golangci-lint and
scripts/lint-checks.sh, so a green golangci-lint alone is not a green
make lint, and that on the pi5 make test dies compiling
modernc.org/sqlite under -race and reruns as go test -race -p 1.

Env var rows were dropped in favour of internal/env.go, which declares
every name, format and consumer; the deployment paragraph defers to
deploy/README.md, keeping only the tripwires it does not carry. Two
derivable sub-package enumerations were cut from the layer table.

Verified by extracting all 227 backticked tokens from the old file: 225
appear verbatim in the new CLAUDE.md, a beacon skill,
pipeline:working-agreement, stack-go, or a repo file. The other two
survive by meaning rather than spelling.

Refs: R21
The Claude Code skill listing truncates a description somewhere above
roughly 935 characters, silently dropping the trailing "Load before"
triggers that make a description work as a load trigger at all.

Rewrite the three oversized descriptions to under 900 characters,
keeping the concrete triggers (directories, symbols, env vars) and
cutting narrative that the skill bodies already carry:

- beacon-collection: 1429 -> 885
- beacon-storage: 1397 -> 809
- beacon-http-api: 1154 -> 825

Every trigger removed from a description still appears in that
skill's body, so nothing is lost from the skill as a whole.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzxZmgGZkK5nbM2L2DiQrr
The standard lens set now includes lens O (owner standards); naming a
count here would have to be corrected in sixteen files each time it
changes, so the delta defers to pipeline:working-agreement instead.
prorochestvo added a commit that referenced this pull request Aug 23, 2026
#140 was opened this morning against 16ae37c and slims CLAUDE.md by
moving depth into the three project skills. It conflicts now, and much
of what it moved has since arrived by other routes — the outlook work
carried its own skill sections, and #141 relocated the SQLite PRAGMA and
write-lock depth. What did not arrive is canon written nowhere else, so
it is taken here verbatim rather than paraphrased.

beacon-collection gains the source kind and options JSON column, the
cmd/doctor operator umbrella, and the reason the Telegram bot bypasses
the proxy in code rather than by configuration: it is the channel that
reports collection failures, so it must not share a failure mode with
what it reports on. beacon-http-api gains the HMAC key/message order,
which is the way round that is easy to invert; the --api-dsn rationale;
and the PublicError contract with the three assertions a controller
error test owes. beacon-storage gains the repository pattern, the
source-deletion cascade and deploy-time schema reconciliation. All four
descriptions are replaced by #140's, whose load triggers are strictly
wider — a skill that does not load is knowledge that is lost.

CLAUDE.md is thinned only where that depth moved, and every tripwire
stays: the inner-mux bypass, the batching, the cascade warning and the
three-assertion rule keep their sentence. 19330 to 17823.

#140's own restructuring of CLAUDE.md into Architecture / Tripwires /
Configuration is not taken. It is a larger editorial change than this,
the file is already under budget, and it should be its own decision
rather than a side effect of salvage.

Nothing was dropped: all 210 backticked spans and 15 figures in the
previous CLAUDE.md still appear in it or in a skill.

Refs: #140

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U6jNuzK5PZrhDWBxB3t2gY
@prorochestvo

Copy link
Copy Markdown
Owner Author

Closing as salvaged rather than merged. 46b4698 (#142) carries the parts of this branch
that had not arrived by another route, taken verbatim rather than paraphrased.

First, the honest part: this branch merged clean against alpha as of 16ae37c. The two
conflicts it carries now — CLAUDE.md and beacon-storage/SKILL.md — are from merges I
landed on those same files afterwards (the long-range outlook, then #139, then #141). I did
not check for open work touching them before doing that.

What carried over

  • beacon-collection — the ## Source rows: kind and options section; the
    ## Operator tooling: cmd/doctor section; and the reason the Telegram bot bypasses the
    proxy in code rather than by configuration — it is the channel that reports collection
    failures, so it must not share a failure mode with the thing it reports on. That reasoning
    existed nowhere else.
  • beacon-http-api — the HMAC scheme with the key/message order called out as easy to
    invert; the --api-dsn rationale; and the whole ## Error rendering section carrying the
    PublicError contract and the three assertions a controller error test owes.
  • beacon-storage — the repository-pattern paragraph, the source-deletion cascade
    subsection, and the deploy-time schema-reconciliation note.
  • All four skill description blocks, which is the change with the longest reach here.
    The wider load triggers — proxyutil, domain.RateSourceOptions, BEACON_CHROMIUM_PATH,
    internal/tools/tgwebapp/initdata.go, internal.PublicError, RequireMigratedSchema,
    stubSQLiteDBThrough — decide whether the knowledge loads at all.

What did not, and why

The restructuring of CLAUDE.md into ## Architecture / ## Tripwires /
## Configuration.
It is a bigger editorial call than a salvage should make on its own,
and the file is now 17823 — 2177 under its own 20k budget — so nothing forces it. Your
## Tripwires section was used as calibration while thinning: every fact it names is present
in the current file.

Also skipped: the passages this branch moves that had already been written by the outlook work
(#131) and by #141 — the long-range forecast section, the content-gated digest, the
weather_forecast_days-is-bounded subsection, the historical-migration-test note, and the
PRAGMA / write-lock depth.

The branch docs/slim-claude-md is left in place, so the restructure can be revisited as its
own change against current alpha rather than rebased through these conflicts.

prorochestvo added a commit that referenced this pull request Aug 24, 2026
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, a sentence or two at a time among material that announces
itself perfectly well. 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 moved 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, which #140's was missing entirely.

Text is moved rather than rewritten wherever it survives, so most of 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
findable.

Nothing was dropped. Of 191 backticked spans, 190 still appear in
CLAUDE.md or a skill; the one casualty is the spelling /api/v1/me/...,
normalised to /api/v1/me/*, the form used in the other four places it
appears. All 15 figures survive.

Also fixed: two code spans that the previous compression pass broke
across a newline. A check that no span crosses one now returns zero.

Refs: #140

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U6jNuzK5PZrhDWBxB3t2gY
@prorochestvo
prorochestvo deleted the docs/slim-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