arc42

name arc42 description Creates or updates arc42 architecture documentation for Java projects (Spring Boot / Quarkus). Analyzes pom.xml, source code, specs, and infrastructure to fill arc42 sections automatically. Supports German and English. Use this skill for "arc42 documentation", "architecture documentation", "document the architecture", "create arc42", "update arc42" or when a project needs structured architecture documentation based on the arc42 template. argument-hint [artifactId] [language: de|en] Arc42 Skill Creates or updates arc42 architecture documentation based on project analysis and a structured interview. Philosophy: Architecture documentation lives with the code. Arc42 sections are filled from actual project artifacts – not from assumptions. Only ask what cannot be derived automatically. What This Skill Does Analyzes the project – evaluates pom.xml, source code, specs, docker-compose, properties Asks for language – German (DE) or English (EN) Fills gaps via interview – only asks what cannot be derived from code Creates or updates – docs/arc42/<artifactId>-arc42.md from template How to Use Create arc42 documentation for my project Update the arc42 docs with the new messaging feature Document the architecture in English arc42 for my Quarkus project Instructions Before every generation: Check .claude/lessons-learned.md Read existing docs/arc42/<artifactId>-arc42.md if present (update mode) Step 1 – Analyze Project (automatic) Before the interview, read and evaluate existing project artifacts: File / Directory Extracted Information Arc42 Section pom.xml groupId, artifactId, framework, dependencies, Java version 1 (Intro), 4 (Strategy), 9 (Decisions) src/main/resources/application.properties or application.yml Ports, DB config, messaging, auth, AI 3 (Context), 7 (Deployment) docker-compose.yml Services, ports, infrastructure 7 (Deployment) specs/*.md Feature specifications, business requirements 1 (Goals), 3 (Context) src/main/java/**/boundary/rest/ REST endpoints (paths, methods, DTOs) 3 (Context), 5 (Building Blocks), 6 (Runtime) src/main/java/**/boundary/messaging/ Messaging consumers/producers 3 (Context), 5 (Building Blocks) src/main/java/**/boundary/ai/ AI Services (LangChain4j) 5 (Building Blocks), 8 (Concepts) src/main/java/**/control/ Services, business logic, AI tools 5 (Building Blocks) src/main/java/**/entity/ Entities, domain model 5 (Building Blocks) src/main/resources/db/migration/ Flyway migrations → DB schema 5 (Building Blocks), 8 (Concepts) src/test/java/**/*ArchitectureTest* Taikai rules → architecture constraints 2 (Constraints), 9 (Decisions) Dockerfile / Helm/ Container config, deployment strategy 7 (Deployment) renovate.json Dependency management strategy 8 (Concepts) docs/*.md Existing documentation All sections Already determined information must not be asked again . Step 2 – Language Selection Ask the user for the documentation language: Option Template Base Output Language Deutsch (DE) templates/arc42-template-DE-plain-markdown/arc42-template-DE.md German headings and prose English (EN) Same template, translated headings English headings and prose If the user already specified the language (e.g. "arc42 in English"), skip this question. Step 3 – Interview (only fill gaps) Only ask what cannot be clearly derived from the source code. Ask all questions at once using a structured format: # Question Arc42 Section Only ask when 1 Brief system description (1–2 sentences: what does it do, for whom?) 1 – Introduction No README or spec present 2 Key quality goals (top 3: e.g. performance, security, maintainability) 1 – Quality Goals Not derivable from tests/specs 3 Stakeholders (who uses it, who decides, who operates?) 1 – Stakeholders Always ask 4 Architecture constraints (organizational, technical, regulatory) 2 – Constraints Always ask 5 External systems (which systems does it interact with?) 3 – Context Not fully derivable from code 6 Key architecture decisions (why this framework, why this DB, why this pattern?) 9 – Decisions Always ask – decisions have reasons 7 Known risks and technical debt 11 – Risks Always ask 8 Should all 12 sections be filled? All Always ask – some sections may be omitted Step 4 – Generate Arc42 Document Create mode: docs/arc42/<artifactId>-arc42.md does not exist → Generate from template, fill all confirmed sections with analyzed + interviewed content. Update mode: docs/arc42/<artifactId>-arc42.md already exists → Read file, update changed/new sections only. → Do not overwrite manually added content by the user. → Add update note: _Last updated: {{DATE}} (arc42)_ Section Mapping Arc42 Section Source Required 1. Introduction and Goals Interview + specs + README Yes 2. Architecture Constraints Interview + Taikai tests + pom.xml Yes 3. Context and Scope REST endpoints, messaging, external systems Yes 4. Solution Strategy Framework choice, patterns (BCE), dependencies Yes 5. Building Block View Package structure (boundary/control/entity) Yes 6. Runtime View REST flows, messaging flows, AI interactions If endpoints present 7. Deployment View Dockerfile, docker-compose, Helm If infra present 8. Cross-cutting Concepts Persistence (Flyway), Auth (Keycloak), AI (LangChain4j), Messaging Yes 9. Architecture Decisions Interview + detected patterns Yes 10. Quality Requirements Quality goals + Taikai rules Yes 11. Risks and Technical Debt Interview Yes 12. Glossary Domain terms from entities and specs If entities present Building Block View (Section 5) – Generation Rules The Building Block View is the most code-dependent section. Generate it as follows: Level 1 – Whitebox Overall System: One box per BCE layer (Boundary, Control, Entity) External systems as black boxes (DB, RabbitMQ, Keycloak, LLM Provider) Use Mermaid diagrams for visualization Level 2 – Per Layer: Boundary: List REST endpoints, messaging consumers, AI services Control: List services, AI tools, RAG components Entity: List JPA entities with key attributes Mermaid Diagrams: Generate Mermaid diagrams for: Context diagram (Section 3) Building block overview (Section 5) Key runtime scenarios (Section 6) Deployment overview (Section 7) Example: graph TB User([User]) --> API[REST API] API --> BC[Boundary Layer] BC --> CC[Control Layer] CC --> EC[Entity Layer] CC --> DB[(PostgreSQL)] CC --> MQ[RabbitMQ] CC --> LLM[LLM Provider] Step 5 – Trigger Background Updates After creating the initial arc42 document, inform the user: The arc42-updater agent can automatically update sections when architecture changes occur. Other skills (java-scaffold, openapi, infrastructure) can trigger it after code generation. References File Description .claude/lessons-learned.md Findings and corrections – check before every generation templates/arc42-template-DE-plain-markdown/arc42-template-DE.md German Markdown template (arc42 v9.0) templates/arc42-template-DE-plain-html/arc42-template.html German HTML template (reference only) Output Path docs/arc42/<artifactId>-arc42.md The docs/arc42/ directory is created if it does not exist. Conventions Language: Selectable – German or English (headings and prose) Filename: <artifactId>-arc42.md in kebab-case Format: Markdown with Mermaid diagrams Diagrams: Mermaid syntax (rendered by GitHub, GitLab, IDE plugins) Version numbers taken from pom.xml – no guessing Passwords / secrets only as placeholders ( <your-secret> ) – never real values Co-Author: <!-- Generated via arc42 · Co-Author: Claude (claude-sonnet-4-6, Anthropic) --> Position in Workflow [spec-feature] optional – business requirements | [openapi] if OpenAPI spec available | [java-scaffold] application: pom.xml, BCE, AI, Flyway | [infrastructure] Dockerfile, docker-compose, Helm | [arc42] <-- architecture documentation | [review] code review | [doc] project documentation (complements arc42) Relationship to doc Skill Aspect arc42 doc Focus Architecture decisions, structure, quality Developer onboarding, API reference, setup Audience Architects, tech leads, reviewers Developers, operators Template arc42 (12 sections) Custom project template Diagrams Mermaid (context, building blocks, deployment) Minimal Updates On architecture changes (via arc42-updater agent) On feature/API changes Both complement each other – arc42 is the "why and how" of architecture, doc is the "how to use and run".