marcel/familienarchiv
1
0
Fork 0
Code Issues 117 Pull Requests 1 Actions 1 Packages Projects Releases Wiki Activity

docs(legibility): migrate CLAUDE.md rules to human docs via pointer comments (DOC-7) #438

New Issue
Closed
opened 2026-05-05 21:09:29 +02:00 by marcel · 1 comment
marcel commented 2026-05-05 21:09:29 +02:00
Owner
Copy Link

Part of #394 (Epic 2 — Documentation). Rubric check: C5.3 (Major). Per #394 Decision Queue D3: migration policy is pointer comments (move content to a human doc; replace the original CLAUDE.md section with a 1-line pointer). Depends on #433 / #435 / #436 / #437 (must exist as migration targets).

Problem

10 CLAUDE.md files contain valuable implementation rules in LLM-targeted form. They're invisible to Anja and Tobias because they don't read CLAUDE.md. After DOC-1..DOC-6 are merged, every rule has a canonical human-doc home. DOC-7 moves the content there and replaces each CLAUDE.md section with a 1-line pointer — preserving CLAUDE.md's utility for LLM agents while making the human doc the canonical source.

Scope

For each CLAUDE.md file, classify each rules section into one of four destinations:

Type Destination Examples
LLM workflow Stays in CLAUDE.md Slash-command conventions, agent guidance, tool usage
Architecture decision docs/ARCHITECTURE.md (#433) or docs/adr/*.md Subsystem boundaries, tech-stack choices
Implementation convention CONTRIBUTING.md (#435) or domain README (#437) Layering rules, @Transactional policy, Svelte 5 patterns, component APIs
Operational rule docs/DEPLOYMENT.md (#436) or docs/infrastructure/*.md Deployment commands, secret management, runtime config

Files in scope (10)

  1. CLAUDE.md (root) — split between #433 (architecture pieces), #435 (commit conventions overlap with COLLABORATING.md), and CLAUDE.md-stays (LLM workflow).
  2. backend/CLAUDE.md — layering rules, @Transactional policy, entity Lombok template → #435.
  3. frontend/CLAUDE.md — Svelte 5 patterns, component APIs (PersonTypeahead, PersonMultiSelect, TagInput), API client pattern → #435 + frontend domain READMEs (#437).
  4. frontend/e2e/CLAUDE.md — test running instructions, seed-data expectations → #435 ## Testing section.
  5. ocr-service/CLAUDE.md — startup behaviour, training token → ocr-service/README.md (#437) + docs/DEPLOYMENT.md (#436).
  6. docs/CLAUDE.md — meta-doc rules. Likely deleted after migration.
  7. scripts/CLAUDE.md — flag dev scripts vs operational scripts; split between #435 (dev) and #436 (ops).
  8. infra/CLAUDE.md — production rules → docs/infrastructure/production-compose.md or #436.
  9. import/CLAUDE.md — mass-import notes → #435 ("Mass import" subsection).
  10. .devcontainer/CLAUDE.md — dev environment → #435 ("Development environment" subsection).

Migration mechanics (per Decision Queue D3)

For every rules section in every CLAUDE.md file:

  1. Move the content to the chosen human-doc home. Rewrite for human audience (the LLM-targeted bullet form often needs prose context).

  2. Replace the original CLAUDE.md section with a 1-line pointer:

    ## Layering Rules
→ See CONTRIBUTING.md#walkthrough-add-a-new-domain

  3. Verify the pointer link resolves to a heading that exists in the target doc.

  4. Do not duplicate: every rule has exactly one home.

  5. Audit docs/STYLEGUIDE.md — per Felix, it overlaps with what CONTRIBUTING.md (#435) covers. Either merge into CONTRIBUTING.md or replace with a pointer.

References

Acceptance criteria

  • Every CLAUDE.md file has been processed (every rules section either migrated with pointer, or justified as LLM-only).
  • Verification grep: grep -rE "DO NOT|MUST NOT|always|never|✅|❌" CLAUDE.md backend/CLAUDE.md frontend/CLAUDE.md frontend/e2e/CLAUDE.md scripts/CLAUDE.md infra/CLAUDE.md import/CLAUDE.md .devcontainer/CLAUDE.md returns no rule-shaped sentences outside → See … pointer blocks.
  • Every pointer link resolves to an existing heading (verifiable by markdown link checker).
  • docs/STYLEGUIDE.md either merged into CONTRIBUTING.md or replaced with a pointer.
  • No content duplication: every rule has exactly one home.
  • Rubric C5.3 PASS verified by reviewer.

Definition of Done

All migrations on main. Verification grep returns clean. All pointer links resolve. Rubric C5.3 PASS.

Part of #394 (Epic 2 — Documentation). Rubric check: C5.3 (Major). Per #394 Decision Queue **D3**: migration policy is **pointer comments** (move content to a human doc; replace the original CLAUDE.md section with a 1-line pointer). Depends on #433 / #435 / #436 / #437 (must exist as migration targets). ## Problem 10 CLAUDE.md files contain valuable implementation rules in LLM-targeted form. They're invisible to **Anja** and **Tobias** because they don't read CLAUDE.md. After DOC-1..DOC-6 are merged, every rule has a canonical human-doc home. DOC-7 moves the content there and replaces each CLAUDE.md section with a 1-line pointer — preserving CLAUDE.md's utility for LLM agents while making the human doc the canonical source. ## Scope For each CLAUDE.md file, classify each rules section into one of four destinations: | Type | Destination | Examples | |---|---|---| | LLM workflow | **Stays** in CLAUDE.md | Slash-command conventions, agent guidance, tool usage | | Architecture decision | `docs/ARCHITECTURE.md` (#433) or `docs/adr/*.md` | Subsystem boundaries, tech-stack choices | | Implementation convention | `CONTRIBUTING.md` (#435) or domain README (#437) | Layering rules, `@Transactional` policy, Svelte 5 patterns, component APIs | | Operational rule | `docs/DEPLOYMENT.md` (#436) or `docs/infrastructure/*.md` | Deployment commands, secret management, runtime config | ### Files in scope (10) 1. `CLAUDE.md` (root) — split between #433 (architecture pieces), #435 (commit conventions overlap with COLLABORATING.md), and CLAUDE.md-stays (LLM workflow). 2. `backend/CLAUDE.md` — layering rules, `@Transactional` policy, entity Lombok template → #435. 3. `frontend/CLAUDE.md` — Svelte 5 patterns, component APIs (`PersonTypeahead`, `PersonMultiSelect`, `TagInput`), API client pattern → #435 + frontend domain READMEs (#437). 4. `frontend/e2e/CLAUDE.md` — test running instructions, seed-data expectations → #435 `## Testing` section. 5. `ocr-service/CLAUDE.md` — startup behaviour, training token → `ocr-service/README.md` (#437) + `docs/DEPLOYMENT.md` (#436). 6. `docs/CLAUDE.md` — meta-doc rules. Likely deleted after migration. 7. `scripts/CLAUDE.md` — flag dev scripts vs operational scripts; split between #435 (dev) and #436 (ops). 8. `infra/CLAUDE.md` — production rules → `docs/infrastructure/production-compose.md` or #436. 9. `import/CLAUDE.md` — mass-import notes → #435 ("Mass import" subsection). 10. `.devcontainer/CLAUDE.md` — dev environment → #435 ("Development environment" subsection). ### Migration mechanics (per Decision Queue D3) For every rules section in every CLAUDE.md file: 1. **Move** the content to the chosen human-doc home. Rewrite for human audience (the LLM-targeted bullet form often needs prose context). 2. **Replace** the original CLAUDE.md section with a 1-line pointer: ```markdown ## Layering Rules → See CONTRIBUTING.md#walkthrough-add-a-new-domain ``` 3. **Verify** the pointer link resolves to a heading that exists in the target doc. 4. **Do not duplicate**: every rule has exactly one home. 5. **Audit `docs/STYLEGUIDE.md`** — per Felix, it overlaps with what CONTRIBUTING.md (#435) covers. Either merge into CONTRIBUTING.md or replace with a pointer. ## References - Parent: #394 - Rubric: C5.3 - **Blocked by**: #433 (DOC-2), #435 (DOC-4), #436 (DOC-5), #437 (DOC-6) — these create the migration targets. - Existing files (in scope): all 10 CLAUDE.md files plus `docs/STYLEGUIDE.md` ## Acceptance criteria - [ ] Every CLAUDE.md file has been processed (every rules section either migrated with pointer, or justified as LLM-only). - [ ] **Verification grep**: `grep -rE "DO NOT|MUST NOT|always|never|✅|❌" CLAUDE.md backend/CLAUDE.md frontend/CLAUDE.md frontend/e2e/CLAUDE.md scripts/CLAUDE.md infra/CLAUDE.md import/CLAUDE.md .devcontainer/CLAUDE.md` returns no rule-shaped sentences outside `→ See …` pointer blocks. - [ ] Every pointer link resolves to an existing heading (verifiable by markdown link checker). - [ ] `docs/STYLEGUIDE.md` either merged into `CONTRIBUTING.md` or replaced with a pointer. - [ ] No content duplication: every rule has exactly one home. - [ ] Rubric C5.3 PASS verified by reviewer. ## Definition of Done All migrations on `main`. Verification grep returns clean. All pointer links resolve. Rubric C5.3 PASS.
marcel added this to the (deleted) milestone 2026-05-05 21:09:29 +02:00
marcel added the P1-highdocumentationlegibility labels 2026-05-05 21:09:49 +02:00
marcel commented 2026-05-05 21:14:25 +02:00
Author
Owner
Copy Link

Duplicate of #401. I created this in error before noticing #401 already existed. #401 carries the persona reviews and per-child Decision Queue; closing this in favor of the existing issue.

**Duplicate of #401.** I created this in error before noticing #401 already existed. #401 carries the persona reviews and per-child Decision Queue; closing this in favor of the existing issue.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
P0-critical
Blocks a core user journey, causes data loss, or is a security/accessibility barrier. Work on this before P1+.
 P1-high
Significant friction on a main user journey; workaround exists but is non-obvious. Next up after P0.
 P2-medium
Noticeable improvement; doesn't block anything; schedule opportunistically.
 P3-later
Cosmetic or parking-lot work; fine to stay open indefinitely.
 audit
Read-only audit / assessment work; produces a report rather than changing code
 bug
Something isn't working
 cleanup
Removal of dead code, vague comments, naming violations, and scratch artifacts
 collaboration
We want to extend the family archive to have more collaboration tools
 conversation
descoped
We will do that later
 devops
documentation
README, ARCHITECTURE, GLOSSARY, CONTRIBUTING, per-domain docs
 epic
Marker for epic-level issues that group multiple child issues
 feature
file-upload
legibility
Codebase Legibility Refactor — preparing the codebase for human evaluation and bus-factor reduction
 notification
person
phase-1: security
Security hygiene — must be done first
 phase-2: container-images
Production-ready multi-stage Docker images
 phase-3: prod-compose
Production compose overlay + Caddy reverse proxy
 phase-4: spring-prod-profile
Spring Boot production configuration profile
 phase-5: backups
Database and object storage backup strategy
 phase-6: deployment-docs
.env.example, DEPLOYMENT.md, runbook
 phase-7: monitoring
Prometheus, Loki, Grafana, Alertmanager
 refactor
Code restructuring without behaviour change
 security
test
ui
UI/UX and accessibility issues
 user
No Label P1-high documentation legibility
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
Jens marcel
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: marcel/familienarchiv#438
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?