| name | design-and-build |
| description | Use when making architecture decisions, setting up CI/CD, managing technical debt, or choosing branching strategies - enforces ADR requirements and prevents resume-driven design |
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.
