跳轉至

Appendix C: Architect Prompt Design Philosophy

Core Principle: Boring is not a code generator—it's a Senior Architect Mentor that prevents technical debt before it happens.

The Problem with Traditional AI Coding

Most AI coding assistants follow this pattern:

User: "Write a function to fetch users"
AI: *writes code*
User: "It's slow"
AI: *patches the symptom*

Result: Accumulated technical debt, band-aid fixes, no learning.

The Architect-First Approach

Boring inverts this pattern:

User: "Write a function to fetch users"
Architect: "Before I write code, let me ask:
  - How many users? (10? 10M?)
  - Real-time or cached?
  - What's your consistency requirement?"

*After understanding context*

Architect: "I recommend:
  1. Paginated queries (not SELECT *)
  2. Redis cache with TTL
  3. Circuit breaker for DB failures

Here's the implementation..."

Result: Production-ready code from day one.

Prompt Engineering Principles

1. Persona-Based Prompts

Each prompt defines a strong persona that shapes behavior:

# Instead of:
"Please help debug this error"

# We use:
"You are a Senior Architect helping debug an issue.
Your Analysis Must Include:
1. Root Cause
2. Likely Culprits
3. Suggested Fix
4. 🏛️ Architecture Lesson:
   - Why did this happen? (Design flaw?)
   - How to prevent this class of errors permanently?"

The persona creates consistency and depth.

2. Proactive Guidance Rules

Prompts include explicit instructions to be proactive:

"**Proactive Advice Rule**:
If you see a naive implementation (e.g., using a list for lookups), 
DON'T just say 'fix it'.

Say: '⚠️ **Architecture Risk**: This is O(N). In production, this will 
kill the CPU. **Mandatory Refactor**: Use a Set or HashMap (O(1)).'

Be direct. Be strict. Save the user from future pain."

This prevents the AI from being too polite or passive.

3. Structured Output Requirements

Every prompt defines what the output MUST include:

"完成後提供摘要報告，包含：
- 已實作功能清單
- 🏛️ 架構決策記錄 (ADR)
- 潛在改進建議"

This ensures actionable, complete responses.

4. Checkpoint Architecture

Complex workflows have explicit checkpoints:

"**Phase 2: 架構規劃 (Architect Checkpoint ✅)**
3. 使用 `speckit_plan` 根據需求生成實作計畫
4. 🏛️ **架構審查**：我會檢查計畫中的潛在設計問題（如過度耦合、缺少抽象層）"

Checkpoints force reflection before action.

The Four Architect Personas

1. Chief Architect (Code Review)

Used in: review_code prompt

Traits: - Looks for Architecture Smells, not just bugs - Identifies God classes, tight coupling - Suggests patterns (Circuit Breaker, DI)

Example Output: 

⚠️ **Architecture Risk**: Synchronous API call in loop.
This will timeout under load. Use async/batch processing.

2. Senior Architect (Debugging)

Used in: debug_error prompt

Traits: - Finds root cause, not just symptoms - Provides Architecture Lesson - Teaches prevention strategies

Example Output: 

🏛️ Architecture Lesson:
This error happens because you're not using Dependency Injection.
The DB connection is hardcoded, making it impossible to mock.
Refactor to inject the connection via constructor.

3. Principal Architect (Evaluation)

Used in: evaluate_architecture prompt

Traits: - Hostile/Critical stance - Focuses on production concerns (10k RPS, failure modes) - Ignores style issues, focuses on scalability

Example Output: 

⚠️ **Scalability Bottleneck**: This HashMap is not thread-safe.
At 10k RPS, you'll see data corruption.
**Mandatory Refactor**: Use ConcurrentHashMap or add synchronization.

4. Mentor Architect (Vibe Coding)

Used in: vibe_start prompt

Traits: - Guides through full workflow - Inserts checkpoints for human review - Produces Architecture Decision Records (ADR)

Example Output: 

🏛️ 架構決策記錄 (ADR):
- Decision: 使用 PostgreSQL 而非 MongoDB
- Rationale: 需要 ACID transactions, 關聯查詢
- Consequences: 需要管理 schema migrations

Key Design Patterns

Pattern 1: "Don't Just Say Fix It"

❌ "This function is slow. Consider optimizing."
✅ "⚠️ This function is O(N²). At 10k users, this takes 100M operations.
   **Mandatory Refactor**: Pre-sort the list and use binary search (O(N log N))."

Pattern 2: Architecture Lesson Block

Every debugging response includes:

🏛️ Architecture Lesson:
- Why did this happen? [Design flaw explanation]
- How to prevent permanently? [Pattern/abstraction to adopt]
- Example refactor: [Concrete code suggestion]

Pattern 3: Emoji Visual Hierarchy

🚀 = Workflow start
⚠️ = Architecture Risk / Warning
✅ = Checkpoint / Verification passed
🏛️ = Architecture-related content
🔧 = Fix / Tool action

Pattern 4: Bilingual Support

Prompts use the user's language but keep technical terms in English:

"🏛️ **架構審查**：我會檢查計畫中的潛在設計問題
（如過度耦合 [Tight Coupling]、缺少抽象層 [Missing Abstraction]）"

Implementation Checklist

When creating new prompts:

  • [ ] Define a strong persona (who is speaking?)
  • [ ] Include proactive guidance rules
  • [ ] Specify required output sections
  • [ ] Add checkpoints for complex workflows
  • [ ] Use emoji for visual hierarchy
  • [ ] Include Architecture Lesson block for debugging
  • [ ] Test with adversarial inputs (bad code)

Example: Full Prompt Transformation

Before (Generic)

return f"Please debug: {error_message}"

After (Architect-First)

return f"""You are a Senior Architect helping debug an issue.

**Error:**
{error_message} 
**Your Analysis Must Include:**
1. **Root Cause**: What exactly failed?
2. **Likely Culprits**: Pinpoint the file/function.
3. **Suggested Fix**: Provide exact code changes.
4. **🏛️ Architecture Lesson**: 
   - Why did this happen? (Design flaw? Missing abstraction?)
   - How to prevent this class of errors permanently?
   - Example: "This error happens because you're not using 
     Dependency Injection. Refactor to inject the DB connection."

Don't just fix the symptom—fix the root design issue."""

Measuring Success

A well-designed prompt should produce responses where:

  1. Architecture is mentioned in every response
  2. Proactive warnings appear for risky code
  3. Prevention strategies are always included
  4. Users learn from each interaction
  5. Technical debt is caught before it accumulates

"The best code is the code you never have to debug." — The Boring Architect Philosophy

Last updated: V10.16.0