From 172bafe202bed9c38a15ef2b7af40b6ab342afeb Mon Sep 17 00:00:00 2001 From: Marcel Date: Thu, 7 May 2026 09:00:58 +0200 Subject: [PATCH] docs(personas): add concrete doc-update trigger tables to Felix and Markus MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Each persona now has a lookup table mapping specific code changes (new Flyway migration, new route, new ErrorCode, etc.) to the exact doc files that must be updated — DB diagrams, C4 diagrams, CLAUDE.md, ADRs, etc. Markus treats missing updates as PR blockers, not concerns. Co-Authored-By: Claude Sonnet 4.6 --- .claude/personas/architect.md | 17 +++++++++++++++++ .claude/personas/developer.md | 18 ++++++++++++++++++ 2 files changed, 35 insertions(+) diff --git a/.claude/personas/architect.md b/.claude/personas/architect.md index f99824d0..6c6d599c 100644 --- a/.claude/personas/architect.md +++ b/.claude/personas/architect.md @@ -410,6 +410,23 @@ Never Kafka for teams under 10 or <100k events/day. Never gRPC inside a monolith 4. Identify missing database-layer enforcement (constraints, RLS) 5. Check transport choices — simpler protocol available? 6. Propose a concrete simpler alternative, not just a critique +7. Verify documentation currency. For each category below, check whether the PR triggered the update. Flag missing updates as blockers. + +| PR contains | Required doc update | +|---|---| +| New Flyway migration adding/removing/renaming a table or column | `docs/architecture/db/db-orm.puml` and `docs/architecture/db/db-relationships.puml` | +| New `@ManyToMany` join table or FK | Both DB diagrams | +| New backend package or domain module | `CLAUDE.md` package table + matching `docs/architecture/c4/l3-backend-*.puml` | +| New controller or service in an existing backend domain | Matching `docs/architecture/c4/l3-backend-*.puml` | +| New SvelteKit route | `CLAUDE.md` route table + matching `docs/architecture/c4/l3-frontend-*.puml` | +| New Docker service or infrastructure component | `docs/architecture/c4/l2-containers.puml` + `docs/DEPLOYMENT.md` | +| New external system integrated | `docs/architecture/c4/l1-context.puml` | +| Auth or upload flow change | `docs/architecture/c4/seq-auth-flow.puml` or `docs/architecture/c4/seq-document-upload.puml` | +| New `ErrorCode` or `Permission` value | `CLAUDE.md` + `docs/ARCHITECTURE.md` | +| New domain concept or term | `docs/GLOSSARY.md` | +| Architectural decision with lasting consequences | New ADR in `docs/adr/` | + +A doc omission is a blocker, not a concern — the PR does not merge until the diagram or text matches the code. ### Designing Systems 1. Start with the data model — get the schema right before application code diff --git a/.claude/personas/developer.md b/.claude/personas/developer.md index 08527fb3..65e14740 100644 --- a/.claude/personas/developer.md +++ b/.claude/personas/developer.md @@ -980,6 +980,24 @@ Mark with `@pytest.mark.asyncio` so pytest runs the coroutine. Without it, the t 5. Refactor — apply clean code, extract if 3+ duplications, rename for intent 6. Repeat for the next behavior 7. When all behaviors are green, review for SOLID violations across the full stack +8. Update documentation before opening the PR. Use the table below to know which doc to touch. + +| What changed in code | Doc(s) to update | +|---|---| +| New Flyway migration adds/removes/renames a table or column | `docs/architecture/db/db-orm.puml` (add/remove entity or attribute) **and** `docs/architecture/db/db-relationships.puml` (add/remove relationship line) | +| New `@ManyToMany` join table or FK relationship | Both DB diagrams above | +| New backend package / domain module | `CLAUDE.md` (package structure table) **and** the matching `docs/architecture/c4/l3-backend-*.puml` diagram for that domain | +| New Spring Boot controller or service in an existing domain | The matching `docs/architecture/c4/l3-backend-*.puml` for that domain | +| New SvelteKit route (`+page.svelte`) | `CLAUDE.md` (route structure section) **and** the matching `docs/architecture/c4/l3-frontend-*.puml` diagram | +| New Docker service / infrastructure component | `docs/architecture/c4/l2-containers.puml` **and** `docs/DEPLOYMENT.md` | +| New external system integrated (new API, new S3 bucket, etc.) | `docs/architecture/c4/l1-context.puml` | +| Auth flow or document-upload flow changes | `docs/architecture/c4/seq-auth-flow.puml` or `docs/architecture/c4/seq-document-upload.puml` | +| New `ErrorCode` enum value | `CLAUDE.md` error handling section **and** `CONTRIBUTING.md` | +| New `Permission` enum value | `CLAUDE.md` security section **and** `docs/ARCHITECTURE.md` | +| New domain term introduced (entity name, status, concept) | `docs/GLOSSARY.md` | +| Architectural decision with lasting consequences (new tech, new transport protocol, new pattern) | New ADR in `docs/adr/` | + +Skip a doc only if the change genuinely does not affect what that doc describes. ### Reviewing Code 1. TDD evidence — are there tests? Do they precede the implementation?