LLM Prompts for Architecture Documentation

Table of Contents

• 1. 🎯 What’s This About?
• 2. 📋 Available Prompts
  • 2.1. Core Architecture Tools
  • 2.2. Comprehensive Documentation Tools
  • 2.3. Risk and Debt Management
  • 2.4. Specialized Prompts
• 3. 🚀 How to Use These Prompts
  • 3.1. 1. Copy & Paste Approach
  • 3.2. 2. Custom AI Assistant Setup
  • 3.3. 3. Integration with docToolchain
• 4. 📖 Examples
• 5. 🔗 Integration Tips
  • 5.1. With Confluence
  • 5.2. With Version Control
  • 5.3. With Project Management
• 6. 🎨 Customization
• 7. 📚 Background & Methodology
  • 7.1. arc42 Template
  • 7.2. Architecture Communication Canvas
  • 7.3. Decision Making
  • 7.4. Quality-Driven Architecture
  • 7.5. Risk-Driven Development
• 8. 🔄 Workflow Integration
  • 8.1. Recommended Usage Sequence
  • 8.2. Continuous Documentation
• 9. 🤝 Contributing
  • 9.1. Contribution Ideas
• 10. 📊 Metrics and Success
  • 10.1. Documentation Quality Metrics
  • 10.2. Process Improvement Metrics
• 11. 📄 License
• 12. 🔗 Related Resources

A collection of carefully crafted prompts to help with software architecture documentation using arc42, docToolchain, and related methodologies. These prompts are designed to work with various LLMs (Claude, ChatGPT, etc.) to streamline architecture documentation workflows.

1. 🎯 What’s This About?

Creating good architecture documentation is challenging. These prompts help you:

• Structure your architecture thinking systematically

• Generate consistent, high-quality documentation

• Follow established methodologies like arc42

• Create visual diagrams and decision records

• Maintain documentation as living artifacts

2. 📋 Available Prompts

2.1. Core Architecture Tools

Prompt	Description	Output Format
Architecture Communication Canvas	Creates a visual canvas summarizing key architecture aspects in one page	AsciiDoc with HTML table
Architecture Decision Record	Structured approach to documenting architecture decisions with Pugh Matrix evaluation	AsciiDoc document

2.2. Comprehensive Documentation Tools

Prompt	Description	Output Format
arc42 Chapter Generator	Step-by-step creation of complete arc42 documentation with quality-driven approach	Multiple AsciiDoc files
Quality Scenarios Builder	Create testable, specific quality requirements using structured scenarios	AsciiDoc quality scenarios

2.3. Risk and Debt Management

Prompt	Description	Output Format
Risk Assessment Matrix	Systematic identification and assessment of architecture risks with mitigation strategies	AsciiDoc risk register
Technical Debt Tracker	Comprehensive technical debt identification, prioritization, and management	AsciiDoc debt register

2.4. Specialized Prompts

Prompt	Description	Output Format
Stakeholder Analysis	include::descriptions/Stakeholder-Analysis-Description.adoc[tag=purpose]	AsciiDoc stakeholder register
Context Diagram Generator	include::descriptions/Context-Diagram-Generator-Description.adoc[tag=purpose]	AsciiDoc with C4-PlantUML diagrams
Solution Strategy Planner	Develop comprehensive solution strategies based on quality goals following arc42 Chapter 4 principles	AsciiDoc strategy document
Deployment View Creator	Design and document comprehensive system deployment architectures following arc42 Chapter 7 principles	AsciiDoc deployment documentation

3. 🚀 How to Use These Prompts

3.1. 1. Copy & Paste Approach

Simply copy the prompt content and paste it into your preferred LLM interface.

3.2. 2. Custom AI Assistant Setup

Use these prompts as system prompts to create specialized AI assistants for architecture work.

3.3. 3. Integration with docToolchain

These prompts are designed to work seamlessly with docToolchain workflows:

• Output is in AsciiDoc format

• Diagrams use PlantUML/Kroki

• Compatible with arc42 template structure

4. 📖 Examples

examples/architecture-communication-canvas-example.adoc

examples/architecture-decision-record-example.adoc

examples/quality-scenarios-example.adoc

5. 🔗 Integration Tips

integration/doctoolchain-integration.adoc

5.1. With Confluence

The generated AsciiDoc can be published directly to Confluence using docToolchain:

./dtcw publishToConfluence

5.2. With Version Control

• Store prompts as documentation templates in your repository

• Version control the generated architecture documents

• Use in CI/CD for automated documentation generation

5.3. With Project Management

• Link architecture decisions to requirements

• Track technical debt in your issue tracking system

• Use risk assessments for project planning

6. 🎨 Customization

These prompts are designed to be customizable:

1. Modify Questions: Adapt the guiding questions to your domain

2. Adjust Output Format: Change AsciiDoc styling or structure

3. Add Custom Sections: Include organization-specific requirements

4. Integrate Tools: Connect with your existing toolchain

7. 📚 Background & Methodology

7.1. arc42 Template

These prompts follow the arc42 template structure, which provides:

• Proven documentation structure

• Clear separation of concerns

• Stakeholder-oriented communication

• Pragmatic approach to architecture documentation

7.2. Architecture Communication Canvas

Based on Gernot Starke’s Architecture Communication Canvas, focusing on:

• Value proposition clarity

• Stakeholder identification

• Core functionality emphasis

• Risk and decision transparency

7.3. Decision Making

Architecture Decision Records (ADRs) use:

• Pugh Matrix for objective evaluation

• Structured problem-solution mapping

• Consequence documentation

• Traceability of architectural reasoning

7.4. Quality-Driven Architecture

Quality Scenarios provide:

• Testable quality requirements

• Objective success criteria

• Architecture decision guidance

• Validation frameworks

7.5. Risk-Driven Development

Risk Assessment includes:

• Systematic risk identification

• Impact and probability evaluation

• Mitigation strategy development

• Continuous risk monitoring

8. 🔄 Workflow Integration

8.1. Recommended Usage Sequence

1. Start with Architecture Communication Canvas - Get the big picture

2. Use arc42 Chapter Generator - Create comprehensive documentation

3. Build Quality Scenarios - Define testable requirements

4. Create Architecture Decision Records - Document key decisions

5. Assess Risks - Identify and mitigate project risks

6. Track Technical Debt - Manage long-term code health

8.2. Continuous Documentation

These prompts support:

• Living Documentation: Keep docs updated as code evolves

• Iterative Refinement: Improve documentation over multiple iterations

• Team Collaboration: Involve multiple stakeholders in documentation creation

• Knowledge Transfer: Maintain institutional knowledge

9. 🤝 Contributing

We welcome contributions! Please:

1. Test Your Prompts: Ensure they work across different LLMs

2. Follow Structure: Use similar format to existing prompts

3. Add Examples: Include sample outputs

4. Document Usage: Explain when and how to use the prompt

5. Consider Integration: How does your prompt work with others?

9.1. Contribution Ideas

• Domain-specific prompts (e.g., microservices, data architecture)

• Integration with specific tools (Jira, GitHub, etc.)

• Visualization enhancements

• Multilingual versions

10. 📊 Metrics and Success

10.1. Documentation Quality Metrics

• Completeness of architecture coverage

• Stakeholder understanding and feedback

• Decision traceability

• Risk mitigation effectiveness

10.2. Process Improvement Metrics

• Time to create documentation

• Documentation maintenance effort

• Team adoption rate

• Knowledge transfer effectiveness

11. 📄 License

These prompts are available under Creative Commons Attribution-ShareAlike 4.0 International License, following the arc42 licensing approach.

12. 🔗 Related Resources

• arc42 Template

• docToolchain

• Architecture Communication Canvas by Gernot Starke

• PlantUML for diagrams

• Kroki for diagram generation

• ADR GitHub Organization for decision records

---

These prompts are maintained by the docToolchain community. For questions or suggestions, please open an issue or contribute directly.