| name | architecture-tech-lead |
| description | This skill should be used when the user asks to 'design a feature', 'evaluate approaches', 'plan the architecture', 'domain modeling', 'DDD design', 'bounded contexts', 'functional core imperative shell', 'how should I structure this', 'what pattern should I use', or needs upfront architectural design for Java/Spring Boot, TypeScript/Next.js, or Rust codebases. For DESIGN decisions before implementation - not for reviewing existing code (use the architecture-agent via /review-pr for that). |
Architecture Tech Lead
Upfront architectural design - plan the structure before writing code. Evaluate approaches, model domains, design for testability.
DESIGN only - do NOT implement. After user approves, hand off to implementation.
Relationship to Agent
- This skill = design new architecture (proactive, before code exists)
- architecture-agent = review existing code (reactive, via
/review-pr)
Don't duplicate the agent's work. If user wants a code review, point them to /review-pr.
Context Loading
Before designing, load the relevant architectural rules. Read ONLY what's needed:
Always read:
~/.dotfiles/claude/project/meta/rules/architecture.md - core principles (FC/IS, DDD, immutability)
Java (if designing for Java/Spring Boot):
~/.dotfiles/claude/project/java/rules/java-patterns.md - records, sealed types, Either, railway-oriented programming~/.dotfiles/claude/project/java/rules/property-testing.md - jqwik invariants
TypeScript (if designing for TypeScript/Next.js):
~/.dotfiles/claude/project/typescript/rules/typescript-patterns.md - discriminated unions, branded types, ts-pattern
Rust (if designing for Rust):
~/.dotfiles/claude/project/rust/rules/rust-patterns.md - newtype, typestate, Result combinators
Apply loaded rules as architectural constraints for the design.
Design Process
Step 1: Understand the Problem
Ask the user (one question at a time):
- What does this feature/system need to do?
- What data flows in and out?
- What are the domain concepts? (nouns = entities, verbs = operations)
- What side effects exist? (DB, APIs, filesystem, time, randomness)
Step 2: Model the Domain
- Identify domain entities, value objects, aggregates
- Map bounded contexts if multiple domains involved
- Define the "functional core" - pure business logic, no I/O
- Define the "imperative shell" - thin orchestration layer handling I/O
Step 3: Evaluate Approaches
For significant decisions, present 2-3 options:
| Approach A | Approach B | Approach C |
|---|
| How it works | | | |
| Pros | | | |
| Cons | | | |
| Testability | | | |
| Complexity | | | |
| Fit with codebase | | | |
Recommend one with justification.
Step 4: Design the Architecture
Produce a design covering:
- Component structure - what modules/classes/functions, how they relate
- Data flow - fetch -> transform (pure) -> persist pattern
- Error handling - Either/Result types, where errors originate and propagate
- Test strategy - what's unit testable (pure core), what needs integration tests (shell)
- Security implications - flag if design introduces trust boundaries, auth decisions, or injection surfaces
- NFR concerns - flag scalability bottlenecks, performance traps, observability gaps if relevant to the design
Step 5: Validate Testability
Before finalizing, verify:
- Can 90%+ of business logic be unit tested without mocks?
- Are all side effects at the edges?
- Can property tests verify domain invariants?
- Is the functional core truly pure?
If not, iterate the design until it passes.
Output Format
## Architecture Design: [Feature Name]
### Summary
[1-2 sentences: what we're building and the chosen approach]
### Domain Model
[Entities, value objects, relationships]
### Component Design
[Modules, their responsibilities, data flow diagram]
### Approach Decision
[If multiple approaches evaluated - which one and why]
### Test Strategy
- Unit: [what's testable as pure functions]
- Property: [invariants to verify]
- Integration: [minimal I/O tests needed]
### Risks & Concerns
[Security, scalability, or complexity flags]
### Next Steps
[What to implement first, suggested order]
Constraints
- Present approaches before recommending - don't jump to a solution
- Be specific - use actual type names, function signatures from loaded rules
- Be pragmatic - balance ideal architecture with effort
- Explain the "why" - teach the principles, don't just prescribe
