Skip to content

docs: move agent doc narrative to on-demand docs - #253

Merged
omznc merged 3 commits into
mainfrom
chore/claude-md-cleanup
Nov 12, 2026
Merged

omznc merged 3 commits into
mainfrom
chore/claude-md-cleanup

Conversation

@omznc

@omznc omznc commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

Problem

A nested CLAUDE.md loads each time that an agent reads a file in its folder. A task in apps/web and packages/core loaded about 68 KB of instructions before work started. Long explanation filled most of that text. Some rules were in a file that does not load for the code that they are about. One fact was out of date.

Changes

Stale facts:

  • packages/core/CLAUDE.md and apps/cli/CLAUDE.md said that apps/web has no tests. It has a bun test suite, and server/*.test.ts drive the real REST route handlers.
  • The root file listed three of the five plans in docs/plans/, and three of the nested CLAUDE.md files.

Misplaced rules:

  • The REST pipeline rules (the order, the PostHog report, the cookie on a write, no CORS, the error mapping) were in apps/cli/CLAUDE.md. They are about apps/web/src/server/api-route.ts, so they did not load for an edit there. They are now in apps/web/CLAUDE.md, with the full text in docs/domains/rest-api.md.
  • The listMembers and listRange gotchas moved from the root to packages/core/CLAUDE.md. The root keeps one line for each.
  • The "bearer plugin stays off" rule now also has a line in packages/core/CLAUDE.md, beside auth/index.ts.

Narrative moved to on-demand docs (verbatim). Each CLAUDE.md keeps a short list of rules and a pointer:

From To
core: Authorization docs/domains/authorization.md
core: Targets and Tracking docs/domains/compliance.md
core: Notifications docs/domains/notifications.md
cli: the API pipeline docs/domains/rest-api.md
cli: install, update, release, codesign, musl docs/domains/cli-distribution.md
web: theme, Display preferences, popups docs/domains/display.md
web: stale chunk reload docs/domains/deployment.md, new last section
root: oxlint plugin sources and amendments tools/oxlint/README.md

Each new doc has a row in the root table, with the files that should make an agent read it.

Removed:

  • The full schema and service file lists in the core layout. The tenancy notes stay: the tables with no organization_id, the services with no Ctx, and PersonCtx.
  • The repeated domain doc lists in core and web. The root table is the one list.
  • The repeated boundary rule in core. The root file has it.

New file: apps/mobile/CLAUDE.md (and its AGENTS.md symlink). It holds the platform design rule (Android M3 Expressive, iOS HIG), the API compatibility rule for the published app, the three timezone test runs, and pointers to the README and docs/domains/mobile.md.

Size

File Before After
CLAUDE.md 18.8 KB 18.6 KB
packages/core/CLAUDE.md 30.2 KB 16.9 KB
apps/web/CLAUDE.md 19.4 KB 16.5 KB
apps/cli/CLAUDE.md 13.8 KB 9.0 KB
apps/mobile/CLAUDE.md none 1.7 KB

A task in apps/web and packages/core now loads 52.1 KB, not 68.4 KB.

Review fixes

  • The mobile compatibility rule is now also in packages/core/CLAUDE.md, beside src/api/. The mobile.md row names packages/api-client and packages/core/src/api/.
  • The deployment.md row names the instance settings again.
  • A path that two workspaces own now has its full path (day-marks.ts, targets.tsx, github-public.ts, github-client.ts, theme.ts).
  • The pipeline text no longer says that every api/v1 route runs api-route.ts. Fourteen route files do not use it, for example meta, openapi[.]json and me/devices.
  • A paragraph in notifications.md rendered inside a list item. It now has a blank line before it.

Checks

  • Each removed line exists in a new file, or it is in the lists above.
  • Each path and section reference in the changed files resolves.
  • bun run check passes. No code changed.

The nested CLAUDE.md files load each time an agent reads a file in
their folder. A web and core task loaded about 68 KB before work
started. Long explanation filled most of it, and some rules were in a
file that does not load for the code that they are about.

Move the authorization matrix, the targets, the notifications, the REST
pipeline, the CLI release, the display preferences and the stale-chunk
reload to docs/domains, and keep a short rule list in each CLAUDE.md.
Move the REST pipeline rules from apps/cli to apps/web, where
server/api-route.ts lives. Fix the claim that apps/web has no tests.
Add apps/mobile/CLAUDE.md with the platform design rule and the API
compatibility rule.
The mobile compatibility rule was only in apps/mobile, but the response
shapes live in packages/core/src/api and packages/api-client. Add the
rule to core and those paths to the mobile.md row. Name the workspace
of the paths that two workspaces could own, add the instance settings
to the deployment.md row, and fix a paragraph that rendered inside a
list item.
The new text said that every api/v1 route runs the api-route pipeline.
Fourteen route files do not use apiRoute or userApiRoute, for example
meta, openapi.json and me/devices, so an agent could assume a guard
that is not there. Say which routes use the pipeline, and write the
full path of github-client.ts and theme.ts, which another workspace
also has.
@omznc
omznc marked this pull request as ready for review November 12, 2026 12:18
@omznc
omznc requested a review from a team as a code owner November 12, 2026 12:18
@omznc
omznc merged commit aca7db9 into main Nov 12, 2026
16 checks passed
@omznc
omznc deleted the chore/claude-md-cleanup branch November 12, 2026 12:21
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