Improve agent bootstrapping #107
Labels
No labels
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
Grandiras/Ponente#107
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Provide some better resources for the task agents to get familiar with the project quickly instead of them having to read a bunch of stuff to get to know it. Also make sure they actually will use those resources. And make sure, those resources get updated when stuff changes.
🤖 On it — follow along in the action run; the reply will link the full session transcript.
📜 Live transcript — updating every ~5 minutes while the task runs.
Pushed to
claude/issue-107.What was wrong
CLAUDE.mdwas the whole manual — 150 KB / ~24,500 words, loaded into every agent's context in full on every task, about 37k tokens spent before any work started, and no entry point except reading all of it. So the practical bootstrapping strategy was "skim and guess".What I did
1.
CLAUDE.mdis now a router (150 KB → 12 KB). What the app is, the commands, the conventions, and a table mapping what you are about to touch → the one page that explains it. Every paragraph it used to hold moved verbatim into twelve topic pages underdocs/(boards-and-permissions,data,live-updates,auth,access-requests,calendar,ui,frontend,i18n,brand,testing,deployment). Only the cross-references between them were rewritten — I diffed every non-empty original line against the new set and accounted for all 14 that changed.2. The actual new resource:
docs/orientation.md— the ten-minute tour. The shape of a request, where everything lives, every service in one line (a table of all 34), the dozen invariants that catch people out (encrypted columns can't be queried, a card carries no board, which-board is a route parameter, entrances are JS-driven not CSS…), and a checklist of what a finished change includes. Reading it plus one topic page is meant to be enough to start.3. Making agents actually use it — three independent nudges.
CLAUDE.mdis auto-loaded and now opens by saying what to read first; a neworientskill whose description is surfaced to every agent at task start (this session's harness picked it up live the moment I wrote it); andREADME.md+ a newAGENTS.mdpointing at the same two files for whoever arrives from the repo page or a tool that readsAGENTS.md.4. Keeping it true:
DocumentationTests, in the unit suite, so CI runs it on every PR. Eight guards — a page that falls out of the router, aCovers:path that no longer exists, a broken relative link anywhere (CLAUDE.md,docs/, README, AGENTS, the skills), a service or an e2e spec described nowhere, a documented route the app doesn't serve, andCLAUDE.mdgrowing back past 16 KB. Plus the convention itself, written intoCLAUDE.mdand the checklist: a change that outdates a page updates that page in the same PR.The route guard already caught a stale claim: the docs described a password form at
POST /local/login, which nothing inProgram.csserves. Corrected — a member with an account on the bundled PDS signs in through the same OAuth form as everyone else, since their PDS is the provider.Verified
dotnet build Ponente.sln -c Release— 0 errors, 0 warnings.dotnet test Ponente.sln -c Release— 295 passed, 0 failed (287 before + 8 new).docs/page,/admin/widgetswritten into a doc,CLAUDE.mdbloated back up, a new unnamed.spec.js, a broken link insideSKILL.md— confirmed each one fails, then reverted and confirmed green.No changelog entry: nothing here is visible to a member.
⏱ 12m 54s · 59 turns · tokens: 138.1k in / 53.5k out (+7117.0k cache-read)
📜 Full session transcript
→ Opened PR: #110