Design and Build
Overview
This skill implements the Technical Solution (TS), Product Integration (PI), and Configuration Management (CM) process areas from the CMMI-based SDLC prescription.
Core principle: Architecture decisions require documentation (ADRs). Emergency shortcuts require retrospective documentation. "Best practice" is never justification - requirements are.
When to Use
Use this skill when:
- Making architecture or design decisions (technology choice, patterns, structure)
- Setting up build/integration systems (CI/CD, deployment pipelines)
- Managing technical debt (tracking, prioritization, paydown)
- Establishing configuration management (branching strategy, release process)
- Facing "should we use X?" questions where X is trendy technology
- Team experiencing git chaos, integration hell, or debt spiral
Do NOT use for:
- Implementation details within existing architecture → Use domain-specific skills (python-engineering, web-backend)
- Testing strategy → Use quality-assurance skill
- Requirements or specification → Use requirements-lifecycle skill
Quick Reference
| Situation |
Primary Reference Sheet |
Key Decision |
| "Should we use microservices?" |
Architecture & Design |
Requires ADR. Use decision framework: team size, domain complexity, ops maturity. |
| "Git workflow is chaos" |
Configuration Management |
Diagnose root cause first. GitFlow (L3 releases) vs GitHub Flow (continuous) vs Trunk (high maturity). Requires ADR. |
| "70% of time on bugs" |
Technical Debt Management |
CODE RED. Feature freeze, architectural audit, classify debt (architectural/tactical/unpayable). |
| "Setting up CI/CD" |
Build & Integration |
Requirements gathering first. Platform choice requires ADR. Start simple, add stages incrementally. |
| "Quick fix vs proper solution" |
Level 2→3→4 Scaling |
Level 3 requires retrospective ADR within 48 hours. Document as HOTFIX with paydown commitment. |
Level-Based Governance
CRITICAL: This skill enforces governance based on project maturity level.
Level Detection
Check for project level in:
CLAUDE.md: CMMI Target Level: 3- User message: "This is a Level 3 project..."
- Default if unspecified: Level 3
ADR Requirements by Level
| Level |
ADR Required For |
Exception Protocol |
| Level 2 |
Major architecture decisions (platform choice, deployment strategy) |
Informal discussion OK, document decision in wiki/README |
| Level 3 |
ALL architectural decisions (tech stack, branching strategy, design patterns, CI/CD platform) |
Emergency HOTFIX: Retrospective ADR within 48 hours mandatory |
| Level 4 |
Everything in L3 + quantitative justification with metrics |
No exceptions - statistical baselines required |
Emergency Exception Protocol (HOTFIX Pattern)
When: Production emergency, immediate fix needed, no time for full ADR process
Level 3 Requirements:
- Fix the emergency (restore service)
- Document the fix in issue tracker with "HOTFIX" label
- Create retrospective ADR within 48 hours:
- Incident timeline
- Why proper fix wasn't feasible
- Technical debt introduced
- Paydown commitment with date (max 2 weeks)
- Track paydown as high-priority ticket
Violation: Skipping retrospective ADR = governance failure. See Enforcement section below.
HOTFIX Frequency Limit: >5 HOTFIXes per month = systemic problem requiring architectural audit, not process exception.
What Counts as "Architectural Decision"? (Level 3)
Architectural decisions (ADR required):
- Technology platform choice (language, framework, database, cache, message queue)
- Branching strategy (GitFlow, GitHub Flow, trunk-based)
- CI/CD platform (GitHub Actions, Azure Pipelines, Jenkins)
- Deployment strategy (blue/green, canary, rolling)
- Design patterns with broad impact (event-driven, microservices, monolith)
- Module boundaries and interfaces (how system decomposes)
- Authentication/authorization approach (OAuth, JWT, session-based)
- Data storage strategy (SQL vs NoSQL, caching strategy, data partitioning)
Implementation details (no ADR required, track in code/PR):
- Specific library choice within chosen framework (e.g., logging library in Python)
- Variable/function naming conventions
- Code organization within module (file structure)
- Test framework choice (if it doesn't affect architecture)
Borderline decisions (when in doubt, write ADR):
- If change affects >3 modules or files → ADR
- If reversal would take >1 day → ADR
- If future developers would ask "why did they choose this?" → ADR
Enforcement and Escalation
Level 3 Requirements:
- Platform enforcement: Branch protection, CI gates, ADR linking
- Process enforcement: ADR review before implementation, HOTFIX tracking
- Metrics: % architectural changes with ADRs (target: 100%)
- Violations escalate: Team lead → Engineering manager → Governance committee
For detailed enforcement mechanisms, escalation paths, and compliance metrics, see level-scaling.md.
Anti-Patterns and Red Flags
Resume-Driven Design
Detection: User says "I've heard X is best practice" or "Everyone uses Y"
Red Flags:
- Technology mentioned before requirements
- Appeal to popularity ("everyone uses microservices")
- Buzzword bingo (serverless, Kubernetes, blockchain)
- Can't articulate WHAT PROBLEM they're solving
Counter:
- "What requirements drive this choice?"
- "What alternatives exist?"
- "Why is current approach inadequate?"
- If they can't answer → "You're doing resume-driven design. Requirements first, technology second."
Forcing function: Require ADR with alternatives analysis. If they can't justify with measurable requirements, ADR review will reject it.
Architecture Astronaut
Detection: Over-engineered solution for simple problem
Red Flags:
- Microservices for CRUD app
- Service mesh for 2 services
- Event sourcing for simple data model
- "Future-proof" without concrete future requirements
Counter: "What's the SIMPLEST solution that meets requirements? Start there. Add complexity when demonstrated need exists, not hypothetically."
Cowboy Coding
Detection: No reviews, no standards, "works on my machine"
Red Flags:
- Skipping pull requests
- Force pushing to main
- No CI/CD
- "I'll add tests later"
Counter: Enforce basic CM practices. Level 2 minimum: branch protection, required PR reviews, CI runs on PRs.
Debt Spiral
Detection: Increasing % of time on bugs, velocity declining
Red Flags:
50% time on bugs = WARNING
60% time on bugs = CODE RED
- Every feature breaks something else
- Team morale declining
Counter: See Technical Debt Management reference sheet. CODE RED triggers feature freeze.
Reference Sheets
Load these on-demand for detailed guidance:
| Reference Sheet |
When to Use |
Link |
| Architecture & Design |
Making technology choices, selecting patterns, designing system structure |
architecture-and-design.md |
| Implementation Standards |
Establishing coding standards, code review process, documentation requirements |
implementation-standards.md |
| Configuration Management |
Git chaos, branching strategy decisions, release management |
configuration-management.md |
| Build & Integration |
Setting up CI/CD, build optimization, deployment pipelines |
build-and-integration.md |
| Technical Debt Management |
Team spending >40% time on bugs, debt accumulating, velocity declining |
technical-debt-management.md |
| Level 2→3→4 Scaling |
Understanding what rigor is appropriate for your project tier |
level-scaling.md |
Common Mistakes
| Mistake |
Why It Fails |
Better Approach |
| "Emergency exempts process" |
Creates pattern where "urgent" = skip governance, accumulating undocumented debt |
Use HOTFIX pattern: retrospective ADR within 48 hours, mandatory |
| "I'll document it later" |
Later never comes, loses audit trail |
Document NOW (ADR takes 15 min) or schedule retrospective (48 hours max) |
| "This is too simple for ADR" |
Simple decisions have big impact, lose rationale for future |
If it's truly simple, ADR takes 10 min. If it takes longer, it wasn't simple. |
| "Everyone uses X, so we should" |
Resume-driven design, not requirements-driven |
Require measurable justification. "Everyone" is not a requirement. |
| "20% debt allocation" when 70% bugs |
Treats crisis as normal problem, ensures slow death |
>60% bugs = CODE RED. Feature freeze, not incremental paydown. |
| "Pick branching strategy" without diagnosis |
Treats symptom (conflicts) not cause (architecture? communication?) |
Root cause analysis FIRST. Git strategy is symptom, not disease. |
| Generic CI/CD template without context |
Wastes time on wrong solution |
Requirements gathering FIRST: build characteristics, deployment context, risk profile |
Integration with Other Skills
| When You're Doing |
Also Use |
For |
| Designing Python architecture |
axiom-python-engineering |
Python-specific patterns and idioms |
| Designing web API |
axiom-web-backend |
REST/GraphQL best practices |
| Making architecture decision |
governance-and-risk |
Formal DAR process for critical choices |
| Setting up testing |
quality-assurance |
Test strategy and coverage |
| Choosing platforms |
platform-integration |
GitHub vs Azure DevOps specifics |
Real-World Impact
Without this skill: Teams experience:
- Undocumented architecture decisions that haunt future developers
- Resume-driven design leading to over-engineered solutions
- Git chaos with daily conflicts and lost work
- Debt spirals consuming 70%+ of time
- Emergency shortcuts becoming permanent anti-patterns
With this skill: Teams achieve:
- Defensible audit trail through ADRs
- Technology choices driven by requirements, not hype
- Structured configuration management reducing conflicts by 80%+
- Early crisis detection preventing debt spirals
- Emergency protocols that maintain governance without blocking urgency
Next Steps
- Determine project level: Check CLAUDE.md or ask user for CMMI target level (default: Level 3)
- Identify situation: Use Quick Reference table to find relevant reference sheet
- Load reference sheet: Read detailed guidance for specific domain
- Enforce ADR requirements: Level 3 requires ADR for architectural decisions - no exceptions without HOTFIX protocol
- Apply decision frameworks: Use systematic evaluation, not gut feelings or hype
- Counter anti-patterns: Watch for resume-driven design, debt spirals, cowboy coding
- Measure success: Establish baseline, set targets, schedule retrospectives
Remember: "Best practice" is never justification. Requirements are. If you can't articulate the requirement, you can't justify the architecture.
1---2name: design-and-build3description: Use when making architecture decisions, setting up CI/CD, managing technical debt, or choosing branching strategies - enforces ADR requirements and prevents resume-driven design4---56# Design and Build78## Overview910This skill implements the **Technical Solution (TS)**, **Product Integration (PI)**, and **Configuration Management (CM)** process areas from the CMMI-based SDLC prescription.1112**Core principle**: Architecture decisions require documentation (ADRs). Emergency shortcuts require retrospective documentation. "Best practice" is never justification - requirements are.1314---1516## When to Use1718Use this skill when:19- Making architecture or design decisions (technology choice, patterns, structure)20- Setting up build/integration systems (CI/CD, deployment pipelines)21- Managing technical debt (tracking, prioritization, paydown)22- Establishing configuration management (branching strategy, release process)23- Facing "should we use X?" questions where X is trendy technology24- Team experiencing git chaos, integration hell, or debt spiral2526**Do NOT use for**:27- Implementation details within existing architecture → Use domain-specific skills (python-engineering, web-backend)28- Testing strategy → Use quality-assurance skill29- Requirements or specification → Use requirements-lifecycle skill3031---3233## Quick Reference3435| Situation | Primary Reference Sheet | Key Decision |36|-----------|------------------------|--------------|37| "Should we use microservices?" | Architecture & Design | Requires ADR. Use decision framework: team size, domain complexity, ops maturity. |38| "Git workflow is chaos" | Configuration Management | Diagnose root cause first. GitFlow (L3 releases) vs GitHub Flow (continuous) vs Trunk (high maturity). Requires ADR. |39| "70% of time on bugs" | Technical Debt Management | CODE RED. Feature freeze, architectural audit, classify debt (architectural/tactical/unpayable). |40| "Setting up CI/CD" | Build & Integration | Requirements gathering first. Platform choice requires ADR. Start simple, add stages incrementally. |41| "Quick fix vs proper solution" | Level 2→3→4 Scaling | Level 3 requires retrospective ADR within 48 hours. Document as HOTFIX with paydown commitment. |4243---4445## Level-Based Governance4647**CRITICAL**: This skill enforces governance based on project maturity level.4849### Level Detection5051Check for project level in:521. `CLAUDE.md`: `CMMI Target Level: 3`532. User message: "This is a Level 3 project..."543. **Default if unspecified**: Level 35556### ADR Requirements by Level5758| Level | ADR Required For | Exception Protocol |59|-------|------------------|-------------------|60| **Level 2** | Major architecture decisions (platform choice, deployment strategy) | Informal discussion OK, document decision in wiki/README |61| **Level 3** | ALL architectural decisions (tech stack, branching strategy, design patterns, CI/CD platform) | Emergency HOTFIX: Retrospective ADR within 48 hours mandatory |62| **Level 4** | Everything in L3 + quantitative justification with metrics | No exceptions - statistical baselines required |6364### Emergency Exception Protocol (HOTFIX Pattern)6566**When**: Production emergency, immediate fix needed, no time for full ADR process6768**Level 3 Requirements**:691. Fix the emergency (restore service)702. Document the fix in issue tracker with "HOTFIX" label713. Create retrospective ADR within **48 hours**:72 - Incident timeline73 - Why proper fix wasn't feasible74 - Technical debt introduced75 - Paydown commitment with date (max 2 weeks)764. Track paydown as high-priority ticket7778**Violation**: Skipping retrospective ADR = governance failure. See Enforcement section below.7980**HOTFIX Frequency Limit**: >5 HOTFIXes per month = systemic problem requiring architectural audit, not process exception.8182### What Counts as "Architectural Decision"? (Level 3)8384**Architectural decisions** (ADR required):85- Technology platform choice (language, framework, database, cache, message queue)86- Branching strategy (GitFlow, GitHub Flow, trunk-based)87- CI/CD platform (GitHub Actions, Azure Pipelines, Jenkins)88- Deployment strategy (blue/green, canary, rolling)89- Design patterns with broad impact (event-driven, microservices, monolith)90- Module boundaries and interfaces (how system decomposes)91- Authentication/authorization approach (OAuth, JWT, session-based)92- Data storage strategy (SQL vs NoSQL, caching strategy, data partitioning)9394**Implementation details** (no ADR required, track in code/PR):95- Specific library choice within chosen framework (e.g., logging library in Python)96- Variable/function naming conventions97- Code organization within module (file structure)98- Test framework choice (if it doesn't affect architecture)99100**Borderline decisions** (when in doubt, write ADR):101- If change affects >3 modules or files → ADR102- If reversal would take >1 day → ADR103- If future developers would ask "why did they choose this?" → ADR104105---106107## Enforcement and Escalation108109**Level 3 Requirements**:110- Platform enforcement: Branch protection, CI gates, ADR linking111- Process enforcement: ADR review before implementation, HOTFIX tracking112- Metrics: % architectural changes with ADRs (target: 100%)113- Violations escalate: Team lead → Engineering manager → Governance committee114115**For detailed enforcement mechanisms, escalation paths, and compliance metrics**, see `level-scaling.md`.116117---118119## Anti-Patterns and Red Flags120121### Resume-Driven Design122123**Detection**: User says "I've heard X is best practice" or "Everyone uses Y"124125**Red Flags**:126- Technology mentioned before requirements127- Appeal to popularity ("everyone uses microservices")128- Buzzword bingo (serverless, Kubernetes, blockchain)129- Can't articulate WHAT PROBLEM they're solving130131**Counter**:1321. "What requirements drive this choice?"1332. "What alternatives exist?"1343. "Why is current approach inadequate?"1354. If they can't answer → "You're doing resume-driven design. Requirements first, technology second."136137**Forcing function**: Require ADR with alternatives analysis. If they can't justify with measurable requirements, ADR review will reject it.138139### Architecture Astronaut140141**Detection**: Over-engineered solution for simple problem142143**Red Flags**:144- Microservices for CRUD app145- Service mesh for 2 services146- Event sourcing for simple data model147- "Future-proof" without concrete future requirements148149**Counter**: "What's the SIMPLEST solution that meets requirements? Start there. Add complexity when demonstrated need exists, not hypothetically."150151### Cowboy Coding152153**Detection**: No reviews, no standards, "works on my machine"154155**Red Flags**:156- Skipping pull requests157- Force pushing to main158- No CI/CD159- "I'll add tests later"160161**Counter**: Enforce basic CM practices. Level 2 minimum: branch protection, required PR reviews, CI runs on PRs.162163### Debt Spiral164165**Detection**: Increasing % of time on bugs, velocity declining166167**Red Flags**:168- >50% time on bugs = WARNING169- >60% time on bugs = CODE RED170- Every feature breaks something else171- Team morale declining172173**Counter**: See Technical Debt Management reference sheet. CODE RED triggers feature freeze.174175---176177## Reference Sheets178179Load these on-demand for detailed guidance:180181| Reference Sheet | When to Use | Link |182|-----------------|-------------|------|183| **Architecture & Design** | Making technology choices, selecting patterns, designing system structure | [architecture-and-design.md](./architecture-and-design.md) |184| **Implementation Standards** | Establishing coding standards, code review process, documentation requirements | [implementation-standards.md](./implementation-standards.md) |185| **Configuration Management** | Git chaos, branching strategy decisions, release management | [configuration-management.md](./configuration-management.md) |186| **Build & Integration** | Setting up CI/CD, build optimization, deployment pipelines | [build-and-integration.md](./build-and-integration.md) |187| **Technical Debt Management** | Team spending >40% time on bugs, debt accumulating, velocity declining | [technical-debt-management.md](./technical-debt-management.md) |188| **Level 2→3→4 Scaling** | Understanding what rigor is appropriate for your project tier | [level-scaling.md](./level-scaling.md) |189190---191192## Common Mistakes193194| Mistake | Why It Fails | Better Approach |195|---------|--------------|-----------------|196| "Emergency exempts process" | Creates pattern where "urgent" = skip governance, accumulating undocumented debt | Use HOTFIX pattern: retrospective ADR within 48 hours, mandatory |197| "I'll document it later" | Later never comes, loses audit trail | Document NOW (ADR takes 15 min) or schedule retrospective (48 hours max) |198| "This is too simple for ADR" | Simple decisions have big impact, lose rationale for future | If it's truly simple, ADR takes 10 min. If it takes longer, it wasn't simple. |199| "Everyone uses X, so we should" | Resume-driven design, not requirements-driven | Require measurable justification. "Everyone" is not a requirement. |200| "20% debt allocation" when 70% bugs | Treats crisis as normal problem, ensures slow death | >60% bugs = CODE RED. Feature freeze, not incremental paydown. |201| "Pick branching strategy" without diagnosis | Treats symptom (conflicts) not cause (architecture? communication?) | Root cause analysis FIRST. Git strategy is symptom, not disease. |202| Generic CI/CD template without context | Wastes time on wrong solution | Requirements gathering FIRST: build characteristics, deployment context, risk profile |203204---205206## Integration with Other Skills207208| When You're Doing | Also Use | For |209|-------------------|----------|-----|210| Designing Python architecture | `axiom-python-engineering` | Python-specific patterns and idioms |211| Designing web API | `axiom-web-backend` | REST/GraphQL best practices |212| Making architecture decision | `governance-and-risk` | Formal DAR process for critical choices |213| Setting up testing | `quality-assurance` | Test strategy and coverage |214| Choosing platforms | `platform-integration` | GitHub vs Azure DevOps specifics |215216---217218## Real-World Impact219220**Without this skill**: Teams experience:221- Undocumented architecture decisions that haunt future developers222- Resume-driven design leading to over-engineered solutions223- Git chaos with daily conflicts and lost work224- Debt spirals consuming 70%+ of time225- Emergency shortcuts becoming permanent anti-patterns226227**With this skill**: Teams achieve:228- Defensible audit trail through ADRs229- Technology choices driven by requirements, not hype230- Structured configuration management reducing conflicts by 80%+231- Early crisis detection preventing debt spirals232- Emergency protocols that maintain governance without blocking urgency233234---235236## Next Steps2372381. **Determine project level**: Check CLAUDE.md or ask user for CMMI target level (default: Level 3)2392. **Identify situation**: Use Quick Reference table to find relevant reference sheet2403. **Load reference sheet**: Read detailed guidance for specific domain2414. **Enforce ADR requirements**: Level 3 requires ADR for architectural decisions - no exceptions without HOTFIX protocol2425. **Apply decision frameworks**: Use systematic evaluation, not gut feelings or hype2436. **Counter anti-patterns**: Watch for resume-driven design, debt spirals, cowboy coding2447. **Measure success**: Establish baseline, set targets, schedule retrospectives245246**Remember**: "Best practice" is never justification. Requirements are. If you can't articulate the requirement, you can't justify the architecture.
tachyon-beep