zhongwei/gh-jamesrochabrun-skills

Fork 0

Files

Zhongwei Li f28999f19c Initial commit

2025-11-29 18:48:55 +08:00

16 KiB

Raw Blame History

Architectural Decision Rubric

Comprehensive framework for choosing the right Anthropic architecture for your project.

Overview

This rubric evaluates seven key dimensions to recommend the optimal combination of Skills, Agents, Prompts, and SDK primitives.

The Seven Dimensions

1. Task Complexity

2. Reusability Requirements

3. Context Management

4. Security & Control

5. Performance Needs

6. Maintenance Burden

7. Time to Market

1. Task Complexity Analysis

Low Complexity (Score: 1-3)

Characteristics:

Single operation or simple workflow
Clear input → output mapping
No dependencies or minimal dependencies
Linear execution (no branching)
1-5 steps maximum
Can be described in one sentence

Recommendation: Direct Prompts

Examples:

"Explain this function"
"Fix this typo"
"Add a comment to this class"
"Format this JSON"
"Translate this error message"

Implementation:

Simple, clear instruction to Claude without additional structure

Medium Complexity (Score: 4-6)

Characteristics:

Multiple related operations
Structured workflow with steps
Some dependencies between steps
Requires reference materials or examples
5-20 steps
Benefits from organization and guidance
Reusable pattern

Recommendation: Skills

Examples:

Generate comprehensive code review
Create design system component
Write technical documentation with examples
Analyze codebase for patterns
Generate test suite following guidelines

Implementation:

skill/
├── SKILL.md (main documentation)
├── references/
│   ├── patterns.md
│   ├── examples.md
│   └── guidelines.md
└── scripts/ (optional)
    └── helper.sh

High Complexity (Score: 7-9)

Characteristics:

Multi-step autonomous workflow
Needs isolated context
Parallel execution beneficial
Different phases with different requirements
20+ steps or multiple parallel tracks
Requires exploration, planning, execution, validation
Different tool permissions per phase

Recommendation: Agents/Subagents

Examples:

Full codebase refactoring
Comprehensive security audit
Multi-file feature implementation
Documentation generation across entire project
Performance optimization analysis and fixes

Implementation:

Main Agent (orchestrator)
├── Explore Subagent (read-only, analysis)
├── Plan Subagent (planning, no execution)
├── Execute Subagent (write permissions)
└── Validate Subagent (testing, verification)

Custom Complexity (Score: 10)

Characteristics:

Unique workflow requirements
System integration needed
Custom tools required
Specific feedback loops
Production deployment
Fine-grained control necessary

Recommendation: SDK Primitives

Examples:

Custom CI/CD integration
Proprietary system automation
Domain-specific code analysis
Production AI features
Specialized agent behaviors

Implementation:

import { Agent, Tool } from 'claude-agent-sdk';

const customAgent = new Agent({
  tools: [customTool1, customTool2],
  workflow: customFeedbackLoop,
  integrations: [ciSystem, deploySystem]
});

2. Reusability Requirements

Single Use (Score: 1-2)

Characteristics:

One-time task
Project-specific
No future reuse expected
Temporal need

Recommendation: Direct Prompts

Examples:

Debug this specific bug
Update this particular file
Answer question about this code

Personal Reuse (Score: 3-4)

Characteristics:

You'll use it multiple times
Personal workflow optimization
Not shared with team

Recommendation: Skills (Personal)

Examples:

Your personal code review checklist
Your preferred refactoring patterns
Your documentation template

Storage: Local .claude/skills/ directory

Team Reuse (Score: 5-7)

Characteristics:

Multiple team members benefit
Team-wide patterns
Shared knowledge
Collaboration value

Recommendation: Skills (Team Plugin)

Examples:

Team coding standards
Project-specific patterns
Shared workflows
Team documentation templates

Storage: Team repository plugin

Organization Reuse (Score: 8-9)

Characteristics:

Cross-team benefit
Company-wide standards
Multiple projects
Organization knowledge

Recommendation: Skills (Organization Marketplace)

Examples:

Company coding standards
Security review guidelines
Architecture patterns
Compliance requirements

Distribution: Internal marketplace

Product Feature (Score: 10)

Characteristics:

End-user facing
Production deployment
Product differentiation
Revenue impact

Recommendation: SDK Primitives

Examples:

AI-powered product feature
Customer-facing automation
Production workflow
SaaS feature

Implementation: Custom SDK integration

3. Context Management Needs

Minimal Context (Score: 1-3)

Characteristics:

Self-contained task
No external references
All info in prompt
< 1000 tokens

Recommendation: Direct Prompts

Example:

Explain this function:
[paste function]

Structured Context (Score: 4-6)

Characteristics:

Reference materials needed
Organized information
Progressive disclosure beneficial
1K-10K tokens

Recommendation: Skills with Progressive Disclosure

Example:

skill/
├── SKILL.md
└── references/
    ├── quick_reference.md (loaded first)
    ├── detailed_patterns.md (loaded on demand)
    └── examples.md (loaded when needed)

Pattern:

Start with minimal context
Load more as needed
Query-based retrieval

Isolated Context (Score: 7-9)

Characteristics:

Separate concerns
Avoid context pollution
Parallel execution
Different contexts per phase
10K+ tokens per context

Recommendation: Agents/Subagents

Example:

Explore Agent: Codebase context (read-only)
Plan Agent: Planning context (insights from explore)
Code Agent: Implementation context (plan + target files)
Review Agent: Validation context (changes + tests)

Benefits:

No context pollution
Clear boundaries
Parallel execution
Optimal token usage

Custom Context (Score: 10)

Characteristics:

Specific context handling
Integration requirements
Custom context sources
Dynamic context loading

Recommendation: SDK Primitives

Example:

const context = await customContextLoader({
  source: proprietarySystem,
  filter: taskSpecific,
  transform: domainFormat
});

4. Security & Control Requirements

Basic Safety (Score: 1-3)

Characteristics:

Read-only operations
No sensitive data
Standard guardrails sufficient
Low risk

Recommendation: Direct Prompts + Skills

Controls:

Standard Claude safety features
No additional restrictions needed

Controlled Access (Score: 4-6)

Characteristics:

Write operations
Specific tool permissions needed
Some sensitive operations
Medium risk

Recommendation: Agents with Tool Restrictions

Controls:

Explore Agent: [Read, Grep, Glob]  // Read-only
Plan Agent: [TodoWrite]             // Planning only
Code Agent: [Read, Edit, Write]     // Code changes
Review Agent: [Bash, Read]          // Testing

Pattern:

Allowlist approach
Minimal permissions
Explicit grants

High Security (Score: 7-9)

Characteristics:

Sensitive operations
Compliance requirements
Audit logging needed
High risk

Recommendation: Agents with Confirmations

Controls:

Agent {
  tools: allowlistOnly,
  confirmations: [
    'git push',
    'deployment',
    'data deletion',
    'sensitive operations'
  ],
  audit: true,
  denylist: dangerousCommands
}

Pattern:

Deny-all default
Explicit confirmations
Audit all operations
Block dangerous commands

Maximum Security (Score: 10)

Characteristics:

Production systems
Financial/medical data
Regulatory compliance
Critical infrastructure

Recommendation: SDK Primitives + Custom Security

Controls:

const secureAgent = new Agent({
  security: {
    denyAll: true,
    allowlist: minimalTools,
    mfa: true,
    audit: comprehensiveLogger,
    encryption: true,
    rateLimits: strict,
    monitoring: realtime,
    rollback: automatic
  }
});

5. Performance Needs

Standard Performance (Score: 1-3)

Characteristics:

User can wait
Not time-sensitive
Occasional use

Recommendation: Any approach

Fast Response (Score: 4-6)

Characteristics:

Quick feedback expected
Interactive use
Multiple requests

Recommendation: Skills with Progressive Disclosure

Optimization:

Load minimal context initially
Query additional info on demand
Cache frequent queries

High Performance (Score: 7-9)

Characteristics:

Real-time or near real-time
Parallel execution beneficial
Resource optimization critical

Recommendation: Agents (Parallel Execution)

Optimization:

Parallel Subagents:
├── Agent 1: File 1-10
├── Agent 2: File 11-20
├── Agent 3: File 21-30
└── Agent 4: Aggregation

Execution: All run simultaneously

Maximum Performance (Score: 10)

Characteristics:

Production SLA requirements
Sub-second responses
High throughput
Resource limits

Recommendation: SDK Primitives + Custom Optimization

Optimization:

const optimizedAgent = new Agent({
  caching: aggressive,
  parallelization: maximum,
  contextCompression: true,
  earlyTermination: true,
  resourceLimits: optimized
});

6. Maintenance Burden

Low Maintenance (Score: 1-3)

Characteristics:

Set and forget
Stable requirements
Minimal updates

Recommendation: Direct Prompts (no maintenance)

Medium Maintenance (Score: 4-6)

Characteristics:

Periodic updates
Evolving patterns
Team contributions

Recommendation: Skills (easy to update)

Maintenance:

Update reference docs
Add new examples
Version control friendly
Clear documentation

High Maintenance (Score: 7-9)

Characteristics:

Regular updates
Multiple contributors
Evolving requirements

Recommendation: Skills + Version Control

Maintenance:

skill/
├── CHANGELOG.md
├── VERSION
├── SKILL.md
└── references/
    └── (versioned docs)

Custom Maintenance (Score: 10)

Characteristics:

Custom codebase
Breaking changes
Integration updates
Production support

Recommendation: SDK Primitives (with CI/CD)

Maintenance:

// Automated testing
// Version management
// Deployment pipeline
// Monitoring and alerts

7. Time to Market

Immediate (Score: 1-3)

Characteristics:

Need it now
No setup time
Quick win

Recommendation: Direct Prompts

Time: Seconds to minutes

Quick (Score: 4-6)

Characteristics:

Hours to days
Some setup acceptable
Reusability valuable

Recommendation: Skills

Time: 1-4 hours to create

Planned (Score: 7-9)

Characteristics:

Days to weeks
Proper planning
Complex requirements

Recommendation: Agents/Subagents

Time: 1-3 days to design and implement

Strategic (Score: 10)

Characteristics:

Weeks to months
Product feature
Full development cycle

Recommendation: SDK Primitives

Time: 1+ weeks to build and deploy

Decision Matrix

Quick Reference Table

Dimension	Prompts	Skills	Agents	SDK
Complexity	Low (1-3)	Medium (4-6)	High (7-9)	Custom (10)
Reusability	Single (1-2)	Team (5-7)	Org (8-9)	Product (10)
Context	Minimal (1-3)	Structured (4-6)	Isolated (7-9)	Custom (10)
Security	Basic (1-3)	Controlled (4-6)	High (7-9)	Max (10)
Performance	Standard (1-3)	Fast (4-6)	High (7-9)	Max (10)
Maintenance	Low (1-3)	Medium (4-6)	High (7-9)	Custom (10)
Time to Market	Immediate (1-3)	Quick (4-6)	Planned (7-9)	Strategic (10)

Scoring Your Project

Step 1: Score Each Dimension

Rate your project on each of the 7 dimensions (1-10).

Step 2: Calculate Weighted Average

Different dimensions may have different importance for your use case.

Default Weights:

Task Complexity: 25%
Reusability: 20%
Context Management: 15%
Security: 15%
Performance: 10%
Maintenance: 10%
Time to Market: 5%

Step 3: Interpret Score

Average Score 1-3: Direct Prompts

Simple, clear instructions
No additional structure

Average Score 4-6: Skills

Organized expertise
Progressive disclosure
Reference materials

Average Score 7-9: Agents/Subagents

Complex workflows
Isolated contexts
Parallel execution

Average Score 10: SDK Primitives

Custom implementation
Full control
Production deployment

Special Cases

Hybrid Architectures

When: Scores span multiple ranges

Solution: Combine approaches

Direct Prompts for simple tasks
Skills for reusable expertise
Agents for complex workflows

Example:

Project with scores:
- Complexity: 7 (Agents)
- Reusability: 5 (Skills)
- Context: 4 (Skills)
- Security: 6 (Skills/Agents)

Recommendation: Agents + Skills
- Use Agents for complex workflows
- Load Skills for domain expertise
- Direct Prompts for simple operations

Decision Tree

Start
│
├─ Is it a simple, one-time task?
│  └─ YES → Direct Prompts
│  └─ NO → Continue
│
├─ Do you need reusable expertise?
│  └─ YES → Continue
│  └─ NO → Continue
│     │
│     ├─ Is it complex with multiple phases?
│     │  └─ YES → Agents
│     │  └─ NO → Direct Prompts
│
├─ Is it complex with isolated contexts needed?
│  └─ YES → Agents
│  └─ NO → Skills
│
├─ Is it a production feature or unique workflow?
│  └─ YES → SDK Primitives
│  └─ NO → Agents or Skills
│
└─ Default → Skills (best balance)

Example Evaluations

Example 1: Code Review Automation

Scores:

Complexity: 5 (structured workflow)
Reusability: 7 (team-wide)
Context: 5 (reference materials)
Security: 4 (read operations)
Performance: 5 (interactive)
Maintenance: 6 (evolving standards)
Time to Market: 5 (hours to setup)

Average: 5.3

Recommendation: Skills

Create code-review skill
Include team standards
Progressive disclosure of guidelines
Reference materials for patterns

Example 2: Codebase Migration

Scores:

Complexity: 9 (multi-phase, autonomous)
Reusability: 3 (one-time migration)
Context: 8 (isolated per phase)
Security: 7 (write operations)
Performance: 8 (parallel execution)
Maintenance: 3 (temporary)
Time to Market: 7 (proper planning)

Average: 6.4

Recommendation: Agents

Despite low reusability, complexity demands Agents
Explore Agent: Analyze codebase
Plan Agent: Create migration strategy
Migrate Agent: Execute changes
Validate Agent: Run tests

Example 3: Quick Bug Fix

Scores:

Complexity: 2 (single fix)
Reusability: 1 (one-time)
Context: 2 (minimal)
Security: 3 (single file change)
Performance: 2 (can wait)
Maintenance: 1 (no maintenance)
Time to Market: 1 (immediate)

Average: 1.7

Recommendation: Direct Prompt

Simple instruction
Fast execution
No overhead

Example 4: AI-Powered Product Feature

Scores:

Complexity: 10 (custom workflow)
Reusability: 10 (product feature)
Context: 10 (custom handling)
Security: 9 (production)
Performance: 9 (SLA requirements)
Maintenance: 10 (ongoing support)
Time to Market: 10 (strategic)

Average: 9.7

Recommendation: SDK Primitives

Custom agent implementation
Production-grade security
Full monitoring and controls
Integration with product

Summary

Use this rubric to:

Score your project on 7 dimensions
Calculate weighted average
Interpret score to get recommendation
Validate with decision tree
Review example evaluations

Key Principle: Start simple, scale complexity as needed.

Remember: The best architecture is the simplest one that meets your requirements.

16 KiB Raw Blame History

Architectural Decision Rubric

Overview

The Seven Dimensions

1. Task Complexity

2. Reusability Requirements

3. Context Management

4. Security & Control

5. Performance Needs

6. Maintenance Burden

7. Time to Market

1. Task Complexity Analysis

Low Complexity (Score: 1-3)

Medium Complexity (Score: 4-6)

High Complexity (Score: 7-9)

Custom Complexity (Score: 10)

2. Reusability Requirements

Single Use (Score: 1-2)

Personal Reuse (Score: 3-4)

Team Reuse (Score: 5-7)

Organization Reuse (Score: 8-9)

Product Feature (Score: 10)

3. Context Management Needs

Minimal Context (Score: 1-3)

Structured Context (Score: 4-6)

Isolated Context (Score: 7-9)

Custom Context (Score: 10)

4. Security & Control Requirements

Basic Safety (Score: 1-3)

Controlled Access (Score: 4-6)

High Security (Score: 7-9)

Maximum Security (Score: 10)

5. Performance Needs

Standard Performance (Score: 1-3)

Fast Response (Score: 4-6)

High Performance (Score: 7-9)

Maximum Performance (Score: 10)

6. Maintenance Burden

Low Maintenance (Score: 1-3)

Medium Maintenance (Score: 4-6)

High Maintenance (Score: 7-9)

Custom Maintenance (Score: 10)

7. Time to Market

Immediate (Score: 1-3)

Quick (Score: 4-6)

Planned (Score: 7-9)

Strategic (Score: 10)

Decision Matrix

Quick Reference Table

Scoring Your Project

Step 1: Score Each Dimension

Step 2: Calculate Weighted Average

Step 3: Interpret Score

Special Cases

Hybrid Architectures

Decision Tree

Example Evaluations

Example 1: Code Review Automation

Example 2: Codebase Migration

Example 3: Quick Bug Fix

Example 4: AI-Powered Product Feature

Summary

16 KiB

Raw Blame History