Architect Blueprint Mode

A pragmatic, opinionated architecture agent that follows structured workflows to analyze codebases, debug issues, and design implementations with a focus on safety, efficiency, and clear communication.

When to Use This Agent

Choose Architect Blueprint Mode when:

• Analyzing complex codebases to understand architecture before making changes
• Debugging issues that require systematic root cause analysis
• Planning multi-file implementations that need careful sequencing
• Conducting architecture reviews with structured feedback
• Working on unfamiliar codebases where you need guided exploration

Consider alternatives when:

• Making quick, targeted code fixes with clear scope (use a code editing tool)
• Writing new code from scratch with well-defined specs (use a standard dev agent)
• Doing pure infrastructure work without application architecture concerns

Quick Start

Copy
# .claude/agents/architect-blueprint-mode.yml
name: Blueprint Mode
model: claude-sonnet-4-20250514
tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
prompt: |
  You are a pragmatic senior engineer. Follow the Blueprint workflow:
  1. Analyze - Read and understand before changing anything
  2. Blueprint - Plan the approach with explicit steps
  3. Construct - Implement changes methodically
  4. Verify - Test and validate the implementation
  Never skip the analysis phase. Always read code before modifying it.

Example invocation:

Copy
claude --agent architect-blueprint-mode "This endpoint returns 500
  errors under load. Analyze the handler, identify the root cause,
  and implement a fix with proper error handling."

Core Concepts

Blueprint Workflows

Workflow	Trigger	Phases
Main	New feature or refactor	Analyze → Blueprint → Construct → Verify
Debug	Bug report or error	Reproduce → Isolate → Root-cause → Fix → Verify
Express	Small, well-scoped change	Read → Change → Verify
Loop	Iterative refinement	Implement → Test → Adjust → Repeat

The Analyze Phase

Copy
## Analysis Checklist
1. Read all files in the change scope
2. Identify dependencies and dependents
3. Map the data flow through affected components
4. Note existing patterns and conventions
5. List constraints (types, tests, linting rules)
6. Flag potential side effects of proposed changes

Blueprint Document Format

Copy
## Blueprint: {Task Description}

### Current State
- What exists today and how it works

### Target State
- What should exist after implementation

### Changes Required
1. {File}: {What changes and why}
2. {File}: {What changes and why}
3. {File}: {What changes and why}

### Risk Assessment
- What could go wrong
- How to mitigate each risk
- Rollback strategy

### Verification
- How to confirm the change works
- Tests to add or update

Decision Framework

For each change, evaluate:
  Safety:     Can this break existing behavior?
  Scope:      Does this change more than necessary?
  Consistency: Does this follow existing patterns?
  Testability: Can this be verified automatically?

If Safety=High Risk → require tests before implementing
If Scope=Too Broad → split into smaller changes
If Consistency=Deviates → document why the deviation is warranted
If Testability=Low → redesign the approach

Configuration

Parameter	Description	Default
workflow	Default workflow mode	Main
analysis_depth	How deep to analyze dependencies	2 levels
require_tests	Mandate test creation for changes	true
max_files_per_change	Alert threshold for change scope	10
verify_before_commit	Run verification after changes	true
document_decisions	Generate decision rationale	true
safety_checks	Pre-change safety validations	Enabled

Best Practices

1. Always read before writing. The most common source of bugs in automated code changes is modifying code you haven't fully read. Read every file you plan to change, plus the files that import from or are imported by those files. The five minutes spent reading saves hours of debugging broken assumptions.

2. Make the smallest change that solves the problem. When debugging, resist the urge to refactor surrounding code. When adding features, resist adding configurability you don't need yet. Small, focused changes are easier to review, test, and roll back. If you see other improvements to make, note them for a separate change.

3. Follow existing patterns even if you disagree with them. Consistency within a codebase is more valuable than individual style preferences. If the codebase uses callbacks and you prefer promises, use callbacks for your change and propose a migration as a separate effort. Pattern inconsistency creates cognitive overhead for every developer who reads the code.

4. Write the verification plan before writing the code. If you cannot describe how to verify a change works correctly, you don't understand the change well enough to implement it. The verification plan often reveals edge cases and integration points you would otherwise miss during implementation.

5. Document the why, not the what. Your blueprint should explain why each change is necessary, not just what files to edit. Code diffs show what changed. Comments show how it works. Only documentation explains why this approach was chosen over alternatives and what constraints shaped the decision.

Common Issues

Analysis paralysis on large codebases. Scope your analysis to the blast radius of the change, not the entire codebase. Start from the file you need to change, trace one level of imports up and down, and stop unless you find something concerning. You can always widen the analysis if the initial scope reveals unexpected dependencies.

Blueprint doesn't survive contact with the code. This happens when the analysis phase missed something. When your implementation diverges from the blueprint, stop and update the blueprint before continuing. The updated blueprint serves as documentation and helps you reason about whether the deviation introduces risks you hadn't considered.

Changes pass tests but break production behavior. Tests only verify what they test. After implementing a change, manually trace the affected code paths end-to-end, paying attention to error handling, edge cases, and concurrent access patterns. Add integration tests for critical paths that unit tests don't cover. If you can't run the application locally, write tests that simulate the production scenario as closely as possible.