docs: teach overzicht, max-lines and the step contract (RD-33)
CLAUDE.md did not name the overzicht context that RD-03 created, and it did not name the max-lines budget that RD-02 enforces. An agent that follows it writes a long page into the wrong context, and meets a red build with no warning. CLAUDE.md now names the context, the @overzicht/* alias, the overzicht -> registratie arrow, the 250-line budget and its glob, and the step-component contract. layers.mdx gains the same arrow. atomic-design.mdx credited eslint.config.mjs with the layer rules. dependency-cruiser enforces them. Each tool is now named for what it does. The page also gains the layer-folder table and the step contract. Four paths were pre-monorepo: three example paths in the ui-component skill, and two citations of libs/shared/src/ui/async, which RD-27 moved to libs/shared/src/ui/molecules/async. npm run ci --full passes: 67 and 45 storybook suites, 306 axe tests. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
@@ -0,0 +1,109 @@
|
||||
# RD-33 — CLAUDE.md, `atomic-design.mdx` and the `ui-component` skill
|
||||
|
||||
Status: done
|
||||
Phase: 5 — fix the docs that describe this flow
|
||||
|
||||
## Why
|
||||
|
||||
This arc added a context, a lint rule and a component contract. Three agent-facing documents
|
||||
still describe the app as it was before.
|
||||
|
||||
CLAUDE.md is the file every agent reads first. It does not name the `overzicht` context that
|
||||
RD-03 created, and it does not name the `max-lines` budget that RD-02 enforces. An agent that
|
||||
follows it writes a 400-line page into the wrong context and meets a red build it was never
|
||||
warned about.
|
||||
|
||||
`atomic-design.mdx` credits `eslint.config.mjs` with the layer rules. Dependency-cruiser
|
||||
enforces them. Crediting the wrong tool sends the next reader to the wrong file.
|
||||
|
||||
## Read first
|
||||
|
||||
- `docs/project/readable-codebase/PLAN.md` §3c (line 604, the step contract), §4a (line 721,
|
||||
the layer move) and phase 5 items 4 and 5 (line 837).
|
||||
- `CLAUDE.md` — sections "1. DDD", "2. Atomic design", "5. Testing" and "Enforced, not just
|
||||
hoped-for".
|
||||
- `libs/shared/docs/atomic-design.mdx:60`, `libs/shared/docs/layers.mdx:41-45`.
|
||||
- `.claude/skills/ui-component/SKILL.md`.
|
||||
|
||||
## Decisions (pre-made, do not relitigate)
|
||||
|
||||
1. **CLAUDE.md gains `overzicht` in three places.** The context list in section 1, the alias
|
||||
list (`@overzicht/*`, which `apps/ssp/tsconfig.json:9` already declares), and the
|
||||
cross-context arrow. The rule in `.dependency-cruiser.ssp.js:8` is `overzicht: ['registratie']`,
|
||||
so the arrow is `overzicht → registratie → libs/shared|beheer`.
|
||||
2. **CLAUDE.md gains the `max-lines` budget** under "Enforced, not just hoped-for", stated as
|
||||
the rule states it: 250 lines, `skipBlankLines` and `skipComments`, over
|
||||
`{apps,libs}/**/*.{page,component,section,step}.ts` (`eslint.config.mjs:64-68`). Say that
|
||||
250 is reachable, not a style-guide default — the dashboard page is 42 lines.
|
||||
3. **CLAUDE.md gains the step-component contract**, in section 2 beside the atomic rules. Three
|
||||
clauses, from PLAN §3c: inputs down, one narrow output up, and `dispatch` is never passed
|
||||
down. Add the corollary: a step gets **no** story of its own, because the wizard's story
|
||||
already mounts it by seeding the machine.
|
||||
4. **The `libs/beheer` title rule is already in CLAUDE.md.** RD-28 landed it. Verify the
|
||||
sentence is there and correct; do not write it a second time.
|
||||
5. **`atomic-design.mdx:60` names the wrong tool.** The layer rules are dependency-cruiser
|
||||
(`npm run dep:check`, `.dependency-cruiser.base.js` plus one file per app). ESLint owns the
|
||||
`any` ban and `max-lines`. Name each tool for what it actually does.
|
||||
6. **`atomic-design.mdx` gains the step contract and the layer table**, so the Storybook reader
|
||||
and the CLAUDE.md reader get the same rule. The table is the shape RD-27 produced:
|
||||
`libs/shared/src/ui/atoms|molecules|organisms/` and `libs/shared/src/layout/`, with the note
|
||||
that `layout/` deliberately holds several layers.
|
||||
7. **`layers.mdx` is missing the `overzicht` arrow.** Its list at lines 41-45 predates RD-03.
|
||||
Add the same arrow as decision 1. This is one line, in the same commit, because the two
|
||||
documents state the same rule and must not disagree.
|
||||
8. **The `ui-component` skill's example paths are pre-monorepo.** Lines 44-46 read
|
||||
`src/app/shared/ui/button/`, `src/app/shared/ui/async/` and `src/app/shared/layout/wizard-shell/`.
|
||||
They are now `libs/shared/src/ui/atoms/button/`, `libs/shared/src/ui/molecules/async/` and
|
||||
`libs/shared/src/layout/wizard-shell/`. Lines 8, 13 and 24 say `shared/ui/` where the folder
|
||||
is now the layer — name the layer folder, because that is the whole point of RD-27.
|
||||
9. **CLAUDE.md:153 and CLAUDE.md:259 carry the same stale-path defect.** Both cite
|
||||
`libs/shared/src/ui/async`, which RD-27 moved to `libs/shared/src/ui/molecules/async`. Fix
|
||||
both in this commit, alongside decision 8's identical fix in the skill file.
|
||||
|
||||
## Files
|
||||
|
||||
- `CLAUDE.md`
|
||||
- `libs/shared/docs/atomic-design.mdx`
|
||||
- `libs/shared/docs/layers.mdx`
|
||||
- `.claude/skills/ui-component/SKILL.md`
|
||||
|
||||
## Steps
|
||||
|
||||
1. CLAUDE.md: decisions 1, 2, 3, and the check in decision 4.
|
||||
2. `atomic-design.mdx`: decisions 5 and 6.
|
||||
3. `layers.mdx`: decision 7.
|
||||
4. `.claude/skills/ui-component/SKILL.md`: decision 8.
|
||||
5. `npm run ci --full`.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] `grep -n overzicht CLAUDE.md` returns the context, the alias and the arrow.
|
||||
- [x] `grep -n max-lines CLAUDE.md` returns the budget, with the glob and the two skip options.
|
||||
- [x] CLAUDE.md states the step contract and the "no story for a step" corollary.
|
||||
- [x] No document credits `eslint.config.mjs` with the layer rules.
|
||||
- [x] Every path in `.claude/skills/ui-component/SKILL.md` resolves.
|
||||
- [x] `npm run ci --full` is green.
|
||||
|
||||
## Verification
|
||||
|
||||
1. `npm run ci --full`. This ticket edits two `.mdx` files, and only `build-storybook` catches
|
||||
a broken MDX import. Plain `npm run ci` does not build Storybook.
|
||||
2. `npm run storybook` — open Foundations, Atomic design and Layers. Both pages render, and the
|
||||
new table is readable at a narrow width.
|
||||
3. `grep -oE '\`[^\`]_(apps|libs)/[^\`]_\`' .claude/skills/ui-component/SKILL.md | tr -d '\`' |
|
||||
xargs ls -d` — every path resolves.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- `ARCHITECTURE.md` (RD-31) and `fp-tea-atomic-design.md` (RD-32).
|
||||
- The other skills in `.claude/skills/`. Only `ui-component` carries stale layer paths.
|
||||
- Renaming `ui/dashboard/`. RD-36 owns that, and it runs after this ticket.
|
||||
|
||||
## Risks
|
||||
|
||||
1. **A broken MDX import passes `npm run ci` and fails CI.** This is PLAN risk 7. Run `--full`.
|
||||
2. **CLAUDE.md is long, and a rule added in the wrong section is a rule nobody finds.** Put
|
||||
each addition in the section that already owns its subject: contexts in 1, the step contract
|
||||
in 2, the lint budget in "Enforced, not just hoped-for".
|
||||
3. **Two documents, one rule.** `layers.mdx` and CLAUDE.md both state the cross-context arrows.
|
||||
Write the same arrow in both, or the next reader gets to choose which one to believe.
|
||||
Reference in New Issue
Block a user