Production-ready arc42 architecture documentation system optimized for AI coding assistants (GitHub Copilot, Cursor, Claude Code, and other LLM tools).
Create professional software architecture documentation with AI assistance using the proven arc42 template. This repository provides comprehensive instructions and prompts specifically designed for Large Language Models to generate high-quality, standards-compliant architecture documentation.
- ✅ Complete arc42 Coverage - All 12 sections with detailed instructions
- 🤖 LLM-Optimized - Specially crafted prompts for GitHub Copilot, Cursor, and Claude Code
- 📊 Q42 Quality Model - Integrated quality framework with 492 attributes across 8 properties
- 🎯 Three Detail Levels - LEAN (minimal), ESSENTIAL (core), THOROUGH (comprehensive)
- ✅ Quality Assurance - Built-in review protocol for validation
- 📚 Official Standards - Based on arc42.org, docs.arc42.org, and quality.arc42.org
- 🔄 Flexible & Pragmatic - "All sections optional" - use what you need
- 🌍 Open Source - Free to use, modify, and contribute
arc42 is the proven, open-source template for software architecture documentation created by Dr. Gernot Starke and Dr. Peter Hruschka. Used in thousands of projects worldwide, it provides a pragmatic, tool-agnostic approach to documenting software architectures.
Core Philosophy:
- Document economically but continuously
- "Painless documentation" - only what stakeholders truly need
- All sections are optional - use what fits your project
- Suitable for agile and traditional environments
-
Clone or download this repository
git clone https://github.com/MSicc/awesome-arc42-copilot.git
-
Choose your section (e.g., Section 1: Introduction and Goals)
- Open
prompts/arc42-section-01-prompt.md - Read the input template
- Fill in your project details
- Open
-
Let your AI assistant generate the documentation
- Copy the prompt into your AI coding assistant
- Provide your project-specific information
- Review and refine the generated output
1. Read: instructions/arc42-section-01-instructions.md
→ Understand what Section 1 should contain
2. Use: prompts/arc42-section-01-prompt.md
→ Generate documentation with your AI assistant
3. Review and refine the generated output
→ Iterate with your AI assistant until satisfiedNote: The quality/REVIEW-PROMPT.md is for maintainers to validate the instruction and prompt files themselves, not for reviewing your generated documentation.
awesome-arc42-copilot/
│
├── README.md # This file
├── LICENSE # MIT License
├── CONTRIBUTING.md # Contribution guidelines
│
├── instructions/ # Human-readable guidelines
│ ├── arc42-global-instructions.md # Overview and philosophy
│ ├── arc42-section-01-instructions.md
│ ├── arc42-section-02-instructions.md
│ └── ... (sections 03-12)
│
├── prompts/ # LLM-optimized prompts
│ ├── arc42-section-01-prompt.md # Introduction & Goals
│ ├── arc42-section-02-prompt.md # Constraints
│ ├── arc42-section-03-prompt.md # Context & Scope
│ └── ... (sections 04-12)
│
└── quality/
└── REVIEW-PROMPT.md # QA protocol for validating instruction/prompt files
Note: The quality/ folder contains the systematic review protocol used to ensure the instruction and prompt files meet arc42 standards. This is for repository maintainers, not for end-users validating their generated documentation.
| Section | Name | Purpose | Required? |
|---|---|---|---|
| 1 | Introduction and Goals | Requirements overview, quality goals, stakeholders | Quality goals mandatory |
| 2 | Constraints | Technical, organizational, political boundaries | Optional |
| 3 | Context and Scope | System boundary and external interfaces | Recommended |
| 4 | Solution Strategy | Fundamental decisions and approaches | Recommended |
| 5 | Building Block View | Static structure (Level-1 mandatory) | Level-1 mandatory |
| 6 | Runtime View | Dynamic behavior scenarios | Optional |
| 7 | Deployment View | Infrastructure and deployment | Optional |
| 8 | Crosscutting Concepts | Overarching patterns and rules | Optional |
| 9 | Architecture Decisions | ADRs with rationale | Recommended |
| 10 | Quality Requirements | Detailed quality scenarios | Recommended |
| 11 | Risks and Technical Debt | Known problems and risks | Optional |
| 12 | Glossary | Domain and technical terminology | Recommended |
Best for: Agile teams, time-constrained projects, evolving systems
Characteristics:
- 1-3 pages per section maximum
- Focus on essential information only
- "Dare to leave gaps" philosophy
Minimum sections:
- Section 1.2: Quality Goals
- Section 3: Context
- Section 5.1: Building Block Level-1
- Section 9: Key Decisions
- Section 12: Glossary
Best for: Most projects - balanced approach
Characteristics:
- Non-negotiable minimum for production systems
- Critical architectural information
- Enables basic understanding
Includes: LEAN plus requirements overview, stakeholders, constraints, solution strategy
Best for: Critical systems, formal environments, audit requirements, large teams
Characteristics:
- Complete documentation across all sections
- Detailed scenarios and specifications
- Multiple refinement levels
- Extensive validation
Includes: All 12 sections fully documented
1. Open prompt file in your editor
2. Fill in project-specific details
3. Use Copilot Chat to generate documentation
4. Refine with follow-up prompts1. Open prompt file in Cursor
2. Select the prompt template
3. Use Cursor's AI to fill in details
4. Iterate until satisfied1. Reference prompt file in your project
2. Provide project context
3. Ask Claude to generate section
4. Review and validate outputThe prompts are designed to work with any LLM tool that supports:
- Markdown understanding
- Structured templates
- Context-aware generation
- ✅ Save 60-80% documentation time
- ✅ Consistent, high-quality output
- ✅ Standards-compliant documentation
- ✅ Focus on decisions, not formatting
- ✅ Shared vocabulary and structure
- ✅ Easy onboarding for new members
- ✅ Reduced documentation debt
- ✅ Better stakeholder communication
- ✅ Standardized architecture documentation
- ✅ Knowledge preservation
- ✅ Improved audit readiness
- ✅ Scalable documentation process
This system integrates the Q42 quality model - a comprehensive framework with 492 quality attributes organized into 8 properties:
| Property | Attributes | Focus |
|---|---|---|
| #reliable | 97 | Availability, Fault Tolerance, Accuracy |
| #flexible | 50 | Adaptability, Maintainability, Extensibility |
| #efficient | 71 | Response Time, Throughput, Resource Usage |
| #usable | 103 | Learnability, Operability, Accessibility |
| #safe | 28 | Risk-free, Fail-safe, Hazard Warnings |
| #secure | 36 | Confidentiality, Integrity, Authentication |
| #suitable | 52 | Functional Completeness, Testability |
| #operable | 55 | Installability, Monitorability, Deployability |
Learn more: quality.arc42.org
We welcome contributions! Here's how you can help:
- 🐛 Report bugs - Found an issue? Open a bug report
- 💡 Suggest improvements - Have ideas? Share them in discussions
- 📝 Improve documentation - Fix typos, add examples, clarify instructions
- 🌟 Share examples - Submit real-world usage examples
- 🔧 Enhance prompts - Improve LLM prompt effectiveness
📖 Read our Contributing Guide → for detailed guidelines on how to get started.
This project is licensed under the MIT License - see the LICENSE file for details.
Note: arc42® is a registered trademark of Dr. Gernot Starke and Dr. Peter Hruschka. This project is based on the freely available arc42 template and is not officially affiliated with arc42.org.
This repository is itself a demonstration of AI-assisted technical writing. The instructions and prompts were created through an iterative collaboration between a human architect (Marco) and Claude (Anthropic's AI assistant).
- Research Phase - Extensive review of official arc42 sources (arc42.org, docs.arc42.org, quality.arc42.org, faq.arc42.org)
- Instruction Development - Section-by-section creation of comprehensive guidelines based on official arc42 standards
- LLM Optimization - Crafting prompts specifically designed for AI coding assistants
- Quality Assurance - Systematic review against arc42 standards using a structured validation protocol
- Iterative Refinement - Multiple review cycles to ensure accuracy and completeness
- ✅ Authenticity First - All content based on official arc42 sources, not invented
- ✅ Standards Compliance - Validated against docs.arc42.org and quality.arc42.org
- ✅ Human Oversight - Human architect provided direction, requirements, and validation
- ✅ AI Efficiency - AI assistant handled research, synthesis, and structured content creation
- ✅ Systematic Quality - Built-in review protocol ensures ongoing accuracy
This collaboration model demonstrates how AI can accelerate documentation work while maintaining professional standards - exactly what this repository enables for architecture documentation.
We believe in transparency about AI involvement in content creation. This repository was:
- Researched by AI from authoritative arc42 sources
- Structured by AI following arc42 methodology
- Directed by human expertise in software architecture
- Validated through systematic quality reviews
- Maintained with ongoing human oversight
The result is production-ready content that respects the original arc42 creators' work while making it more accessible through modern AI tools.
- arc42 Template - Created by Dr. Gernot Starke and Dr. Peter Hruschka
- Official Sources:
- arc42.org - Main website
- docs.arc42.org - Official documentation
- quality.arc42.org - Q42 quality model
- faq.arc42.org - Frequently asked questions
- Claude (Anthropic) - AI assistant used in creating this repository's content
- Contributors - See CONTRIBUTORS.md for everyone who has helped make this project better
- Architecture Decision Records (ADR)
- C4 Model - Recommended for diagrams
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Questions: Open a discussion or issue
If you find this project helpful, please consider giving it a star! ⭐
- ✅ Version 1.0 - Complete arc42 coverage (all 12 sections)
- ✅ Production Ready - Quality assured and validated
- ✅ Actively Maintained - Regular updates and improvements
- ✅ Community Driven - Open to contributions
Goal: Incorporate improvements identified during systematic quality reviews
- 🔄 Refine Instructions - Address findings from section-by-section validation
- 🔄 Enhance Prompts - Improve LLM effectiveness based on review feedback
- 🔄 Update Examples - Add more concrete, real-world examples
- 🔄 Cross-Section Consistency - Ensure perfect alignment between related sections
Goal: Battle-test the system on an actual project
- 📋 Use Case: persona-template MCP Server
- Project: Developer tool for managing persona preferences and projects across AI providers
- Purpose: Document MCP (Model Context Protocol) server architecture
- Benefit: Validate arc42-copilot system on real infrastructure project
- Output: Complete example arc42 documentation in repository
What is persona-template? An upcoming project that provides developers an easy way to move persona preferences and software projects between AI providers (GitHub Copilot, Cursor, Claude, etc.). The MCP server architecture will be documented using this arc42-copilot system, serving as both:
- Real-world validation of our methodology
- Reference implementation for others
- Example of arc42 documentation for AI infrastructure
Goal: Expand examples and community contributions
- 📚 More Examples - Additional real-world documentation samples
- 🎯 Domain-Specific Templates - Variations for microservices, embedded systems, data platforms
- 🌍 Community Contributions - User-submitted examples and improvements
- 📖 Tutorial Content - Video walkthroughs and step-by-step guides
- 🔌 Tool Integrations - Plugins for popular IDEs and documentation tools
- 🧪 Test it - Use the system on your project and share feedback
- 📝 Contribute examples - Submit your arc42 documentation as examples
- 🐛 Report issues - Help us identify and fix problems
- 💡 Suggest improvements - Share ideas for better prompts or instructions
- ⭐ Star the repo - Help others discover this resource
Made with ❤️ for the software architecture community
Bringing AI-powered efficiency to architecture documentation while maintaining the highest standards of quality and compliance.