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.
Reference: See docs/sdlc-prescription-cmmi-levels-2-4.md Section 3.2 for complete policy and practice definitions.
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---5
6# Design and Build
7
8## Overview
9
10This skill implements the **Technical Solution (TS)**, **Product Integration (PI)**, and **Configuration Management (CM)** process areas from the CMMI-based SDLC prescription.
11
12**Core principle**: Architecture decisions require documentation (ADRs). Emergency shortcuts require retrospective documentation. "Best practice" is never justification - requirements are.
13
14**Reference**: See `docs/sdlc-prescription-cmmi-levels-2-4.md` Section 3.2 for complete policy and practice definitions.
15
16---
17
18## When to Use
19
20Use this skill when:
21- Making architecture or design decisions (technology choice, patterns, structure)
22- Setting up build/integration systems (CI/CD, deployment pipelines)
23- Managing technical debt (tracking, prioritization, paydown)
24- Establishing configuration management (branching strategy, release process)
25- Facing "should we use X?" questions where X is trendy technology
26- Team experiencing git chaos, integration hell, or debt spiral
27
28**Do NOT use for**:
29- Implementation details within existing architecture → Use domain-specific skills (python-engineering, web-backend)
30- Testing strategy → Use quality-assurance skill
31- Requirements or specification → Use requirements-lifecycle skill
32
33---
34
35## Quick Reference
36
37| Situation | Primary Reference Sheet | Key Decision |
38|-----------|------------------------|--------------|
39| "Should we use microservices?" | Architecture & Design | Requires ADR. Use decision framework: team size, domain complexity, ops maturity. |
40| "Git workflow is chaos" | Configuration Management | Diagnose root cause first. GitFlow (L3 releases) vs GitHub Flow (continuous) vs Trunk (high maturity). Requires ADR. |
41| "70% of time on bugs" | Technical Debt Management | CODE RED. Feature freeze, architectural audit, classify debt (architectural/tactical/unpayable). |
42| "Setting up CI/CD" | Build & Integration | Requirements gathering first. Platform choice requires ADR. Start simple, add stages incrementally. |
43| "Quick fix vs proper solution" | Level 2→3→4 Scaling | Level 3 requires retrospective ADR within 48 hours. Document as HOTFIX with paydown commitment. |
44
45---
46
47## Level-Based Governance
48
49**CRITICAL**: This skill enforces governance based on project maturity level.
50
51### Level Detection
52
53Check for project level in:
541. `CLAUDE.md`: `CMMI Target Level: 3`
552. User message: "This is a Level 3 project..."
563. **Default if unspecified**: Level 3
57
58### ADR Requirements by Level
59
60| Level | ADR Required For | Exception Protocol |
61|-------|------------------|-------------------|
62| **Level 2** | Major architecture decisions (platform choice, deployment strategy) | Informal discussion OK, document decision in wiki/README |
63| **Level 3** | ALL architectural decisions (tech stack, branching strategy, design patterns, CI/CD platform) | Emergency HOTFIX: Retrospective ADR within 48 hours mandatory |
64| **Level 4** | Everything in L3 + quantitative justification with metrics | No exceptions - statistical baselines required |
65
66### Emergency Exception Protocol (HOTFIX Pattern)
67
68**When**: Production emergency, immediate fix needed, no time for full ADR process
69
70**Level 3 Requirements**:
711. Fix the emergency (restore service)
722. Document the fix in issue tracker with "HOTFIX" label
733. Create retrospective ADR within **48 hours**:
74 - Incident timeline
75 - Why proper fix wasn't feasible
76 - Technical debt introduced
77 - Paydown commitment with date (max 2 weeks)
784. Track paydown as high-priority ticket
79
80**Violation**: Skipping retrospective ADR = governance failure. See Enforcement section below.
81
82**HOTFIX Frequency Limit**: >5 HOTFIXes per month = systemic problem requiring architectural audit, not process exception.
83
84### What Counts as "Architectural Decision"? (Level 3)
85
86**Architectural decisions** (ADR required):
87- Technology platform choice (language, framework, database, cache, message queue)
88- Branching strategy (GitFlow, GitHub Flow, trunk-based)
89- CI/CD platform (GitHub Actions, Azure Pipelines, Jenkins)
90- Deployment strategy (blue/green, canary, rolling)
91- Design patterns with broad impact (event-driven, microservices, monolith)
92- Module boundaries and interfaces (how system decomposes)
93- Authentication/authorization approach (OAuth, JWT, session-based)
94- Data storage strategy (SQL vs NoSQL, caching strategy, data partitioning)
95
96**Implementation details** (no ADR required, track in code/PR):
97- Specific library choice within chosen framework (e.g., logging library in Python)
98- Variable/function naming conventions
99- Code organization within module (file structure)
100- Test framework choice (if it doesn't affect architecture)
101
102**Borderline decisions** (when in doubt, write ADR):
103- If change affects >3 modules or files → ADR
104- If reversal would take >1 day → ADR
105- If future developers would ask "why did they choose this?" → ADR
106
107---
108
109## Enforcement and Escalation
110
111**Level 3 Requirements**:
112- Platform enforcement: Branch protection, CI gates, ADR linking
113- Process enforcement: ADR review before implementation, HOTFIX tracking
114- Metrics: % architectural changes with ADRs (target: 100%)
115- Violations escalate: Team lead → Engineering manager → Governance committee
116
117**For detailed enforcement mechanisms, escalation paths, and compliance metrics**, see `level-scaling.md`.
118
119---
120
121## Anti-Patterns and Red Flags
122
123### Resume-Driven Design
124
125**Detection**: User says "I've heard X is best practice" or "Everyone uses Y"
126
127**Red Flags**:
128- Technology mentioned before requirements
129- Appeal to popularity ("everyone uses microservices")
130- Buzzword bingo (serverless, Kubernetes, blockchain)
131- Can't articulate WHAT PROBLEM they're solving
132
133**Counter**:
1341. "What requirements drive this choice?"
1352. "What alternatives exist?"
1363. "Why is current approach inadequate?"
1374. If they can't answer → "You're doing resume-driven design. Requirements first, technology second."
138
139**Forcing function**: Require ADR with alternatives analysis. If they can't justify with measurable requirements, ADR review will reject it.
140
141### Architecture Astronaut
142
143**Detection**: Over-engineered solution for simple problem
144
145**Red Flags**:
146- Microservices for CRUD app
147- Service mesh for 2 services
148- Event sourcing for simple data model
149- "Future-proof" without concrete future requirements
150
151**Counter**: "What's the SIMPLEST solution that meets requirements? Start there. Add complexity when demonstrated need exists, not hypothetically."
152
153### Cowboy Coding
154
155**Detection**: No reviews, no standards, "works on my machine"
156
157**Red Flags**:
158- Skipping pull requests
159- Force pushing to main
160- No CI/CD
161- "I'll add tests later"
162
163**Counter**: Enforce basic CM practices. Level 2 minimum: branch protection, required PR reviews, CI runs on PRs.
164
165### Debt Spiral
166
167**Detection**: Increasing % of time on bugs, velocity declining
168
169**Red Flags**:
170- >50% time on bugs = WARNING
171- >60% time on bugs = CODE RED
172- Every feature breaks something else
173- Team morale declining
174
175**Counter**: See Technical Debt Management reference sheet. CODE RED triggers feature freeze.
176
177---
178
179## Reference Sheets
180
181Load these on-demand for detailed guidance:
182
183| Reference Sheet | When to Use | Link |
184|-----------------|-------------|------|
185| **Architecture & Design** | Making technology choices, selecting patterns, designing system structure | [architecture-and-design.md](./architecture-and-design.md) |
186| **Implementation Standards** | Establishing coding standards, code review process, documentation requirements | [implementation-standards.md](./implementation-standards.md) |
187| **Configuration Management** | Git chaos, branching strategy decisions, release management | [configuration-management.md](./configuration-management.md) |
188| **Build & Integration** | Setting up CI/CD, build optimization, deployment pipelines | [build-and-integration.md](./build-and-integration.md) |
189| **Technical Debt Management** | Team spending >40% time on bugs, debt accumulating, velocity declining | [technical-debt-management.md](./technical-debt-management.md) |
190| **Level 2→3→4 Scaling** | Understanding what rigor is appropriate for your project tier | [level-scaling.md](./level-scaling.md) |
191
192---
193
194## Common Mistakes
195
196| Mistake | Why It Fails | Better Approach |
197|---------|--------------|-----------------|
198| "Emergency exempts process" | Creates pattern where "urgent" = skip governance, accumulating undocumented debt | Use HOTFIX pattern: retrospective ADR within 48 hours, mandatory |
199| "I'll document it later" | Later never comes, loses audit trail | Document NOW (ADR takes 15 min) or schedule retrospective (48 hours max) |
200| "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. |
201| "Everyone uses X, so we should" | Resume-driven design, not requirements-driven | Require measurable justification. "Everyone" is not a requirement. |
202| "20% debt allocation" when 70% bugs | Treats crisis as normal problem, ensures slow death | >60% bugs = CODE RED. Feature freeze, not incremental paydown. |
203| "Pick branching strategy" without diagnosis | Treats symptom (conflicts) not cause (architecture? communication?) | Root cause analysis FIRST. Git strategy is symptom, not disease. |
204| Generic CI/CD template without context | Wastes time on wrong solution | Requirements gathering FIRST: build characteristics, deployment context, risk profile |
205
206---
207
208## Integration with Other Skills
209
210| When You're Doing | Also Use | For |
211|-------------------|----------|-----|
212| Designing Python architecture | `axiom-python-engineering` | Python-specific patterns and idioms |
213| Designing web API | `axiom-web-backend` | REST/GraphQL best practices |
214| Making architecture decision | `governance-and-risk` | Formal DAR process for critical choices |
215| Setting up testing | `quality-assurance` | Test strategy and coverage |
216| Choosing platforms | `platform-integration` | GitHub vs Azure DevOps specifics |
217
218---
219
220## Real-World Impact
221
222**Without this skill**: Teams experience:
223- Undocumented architecture decisions that haunt future developers
224- Resume-driven design leading to over-engineered solutions
225- Git chaos with daily conflicts and lost work
226- Debt spirals consuming 70%+ of time
227- Emergency shortcuts becoming permanent anti-patterns
228
229**With this skill**: Teams achieve:
230- Defensible audit trail through ADRs
231- Technology choices driven by requirements, not hype
232- Structured configuration management reducing conflicts by 80%+
233- Early crisis detection preventing debt spirals
234- Emergency protocols that maintain governance without blocking urgency
235
236---
237
238## Next Steps
239
2401. **Determine project level**: Check CLAUDE.md or ask user for CMMI target level (default: Level 3)
2412. **Identify situation**: Use Quick Reference table to find relevant reference sheet
2423. **Load reference sheet**: Read detailed guidance for specific domain
2434. **Enforce ADR requirements**: Level 3 requires ADR for architectural decisions - no exceptions without HOTFIX protocol
2445. **Apply decision frameworks**: Use systematic evaluation, not gut feelings or hype
2456. **Counter anti-patterns**: Watch for resume-driven design, debt spirals, cowboy coding
2467. **Measure success**: Establish baseline, set targets, schedule retrospectives
247
248**Remember**: "Best practice" is never justification. Requirements are. If you can't articulate the requirement, you can't justify the architecture.
majiayu000