commit 1dce17ca1b93ee7d6f164f7ed657645ccab66829 Author: Zhongwei Li Date: Sat Nov 29 18:49:02 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..12c5be0 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "anthropic-architect", + "description": "Determine the best Anthropic architecture for your project by analyzing requirements and recommending the optimal combination of Skills, Agents, Prompts, and SDK primitives.", + "version": "0.0.0-2025.11.28", + "author": { + "name": "James Rochabrun", + "email": "jamesrochabrun@gmail.com" + }, + "skills": [ + "./skills/anthropic-architect" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..67dc29e --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# anthropic-architect + +Determine the best Anthropic architecture for your project by analyzing requirements and recommending the optimal combination of Skills, Agents, Prompts, and SDK primitives. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..8441745 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,60 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:jamesrochabrun/skills:anthropic-architect", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "db28313b07190023854cff019ee992e3a181940d", + "treeHash": "52a462f2b0db75c3520fd5df3935d21b4e6364d2a1bb4ee7dab4625bc21e7874", + "generatedAt": "2025-11-28T10:17:43.330165Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "anthropic-architect", + "description": "Determine the best Anthropic architecture for your project by analyzing requirements and recommending the optimal combination of Skills, Agents, Prompts, and SDK primitives." + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "45686eb5fb0efef4def17fb29561c36b3c80638523c9670821ccbf81201cb623" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "b743ad08277074dbb8556d565fd7387a2d8f3fcbc9818237ac3d01e2156a185f" + }, + { + "path": "skills/anthropic-architect/SKILL.md", + "sha256": "2e70020e21eff7f27404fee64adc372f69c99929da86decd5e9f959ff1c0eaf4" + }, + { + "path": "skills/anthropic-architect/references/use_case_examples.md", + "sha256": "48dde578e874e37a0512cbd4e7d116d97dbb18509eb1b6ccab75c562d05f8a3b" + }, + { + "path": "skills/anthropic-architect/references/architectural_patterns.md", + "sha256": "4f246500ea6f89ca08de03a1f4c570f10059a694c732aa24d34e37a614270692" + }, + { + "path": "skills/anthropic-architect/references/decision_rubric.md", + "sha256": "78b82fa23df102e7255754e6b16cb11e2a470601d2735d0f9f20e67caa4bb7ae" + }, + { + "path": "skills/anthropic-architect/references/best_practices.md", + "sha256": "8e6f02508638ebb9868cc23f8a1320a35cd60160996ab0e25b4d3771f0106971" + } + ], + "dirSha256": "52a462f2b0db75c3520fd5df3935d21b4e6364d2a1bb4ee7dab4625bc21e7874" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/anthropic-architect/SKILL.md b/skills/anthropic-architect/SKILL.md new file mode 100644 index 0000000..d5027e4 --- /dev/null +++ b/skills/anthropic-architect/SKILL.md @@ -0,0 +1,571 @@ +--- +name: anthropic-architect +description: Determine the best Anthropic architecture for your project by analyzing requirements and recommending the optimal combination of Skills, Agents, Prompts, and SDK primitives. +--- + +# Anthropic Architect + +Expert architectural guidance for Anthropic-based projects. Analyze your requirements and receive tailored recommendations on the optimal architecture using Skills, Agents, Subagents, Prompts, and SDK primitives. + +## What This Skill Does + +Helps you design the right Anthropic architecture for your project by: +- **Analyzing project requirements** - Understanding complexity, scope, and constraints +- **Recommending architectures** - Skills vs Agents vs Prompts vs SDK primitives +- **Applying decision rubrics** - Data-driven architectural choices +- **Following best practices** - 2025 Anthropic patterns and principles +- **Progressive disclosure design** - Efficient context management +- **Security considerations** - Safe, controllable AI systems + +## Why Architecture Matters + +**Without proper architecture:** +- Inefficient context usage and high costs +- Poor performance and slow responses +- Security vulnerabilities and risks +- Difficult to maintain and scale +- Agents reading entire skill contexts unnecessarily +- Mixed concerns and unclear boundaries + +**With engineered architecture:** +- Optimal context utilization +- Fast, focused responses +- Secure, controlled operations +- Easy to maintain and extend +- Progressive disclosure of information +- Clear separation of concerns +- Scalable and reusable components + +## Quick Start + +### Analyze Your Project + +``` +Using the anthropic-architect skill, help me determine the best +architecture for: [describe your project] + +Requirements: +- [List your key requirements] +- [Complexity level] +- [Reusability needs] +- [Security constraints] +``` + +### Get Architecture Recommendation + +The skill will provide: +1. **Recommended architecture** - Specific primitives to use +2. **Decision reasoning** - Why this architecture fits +3. **Implementation guidance** - How to build it +4. **Best practices** - What to follow +5. **Example patterns** - Similar successful architectures + +## The Four Anthropic Primitives + +### 1. Skills (Prompt-Based Meta-Tools) + +**What:** Organized folders of instructions, scripts, and resources that agents can discover and load dynamically. + +**When to use:** +- ✅ Specialized domain knowledge needed +- ✅ Reusable across multiple projects +- ✅ Complex, multi-step workflows +- ✅ Reference materials required +- ✅ Progressive disclosure beneficial + +**When NOT to use:** +- ❌ Simple, one-off tasks +- ❌ Project-specific logic only +- ❌ No need for reusability + +**Example use cases:** +- Prompt engineering expertise +- Design system generation +- Code review guidelines +- Domain-specific knowledge (finance, medical, legal) + +### 2. Agents/Subagents (Autonomous Task Handlers) + +**What:** Specialized agents with independent system prompts, dedicated context windows, and specific tool permissions. + +**When to use:** +- ✅ Complex, multi-step autonomous tasks +- ✅ Need for isolated context +- ✅ Different tool permissions required +- ✅ Parallel task execution +- ✅ Specialized expertise per task type + +**When NOT to use:** +- ❌ Simple queries or lookups +- ❌ Shared context required +- ❌ Sequential dependencies +- ❌ Resource-constrained environments + +**Example use cases:** +- Code exploration and analysis +- Test generation and execution +- Documentation generation +- Security audits +- Performance optimization + +### 3. Direct Prompts (Simple Instructions) + +**What:** Clear, explicit instructions passed directly to Claude without additional structure. + +**When to use:** +- ✅ Simple, straightforward tasks +- ✅ One-time operations +- ✅ Quick questions or clarifications +- ✅ No need for specialization +- ✅ Minimal context required + +**When NOT to use:** +- ❌ Complex, multi-step processes +- ❌ Need for reusability +- ❌ Requires domain expertise +- ❌ Multiple related operations + +**Example use cases:** +- Code explanations +- Quick refactoring +- Simple bug fixes +- Documentation updates +- Direct questions + +### 4. SDK Primitives (Custom Workflows) + +**What:** Low-level building blocks from the Claude Agent SDK to create custom agent workflows. + +**When to use:** +- ✅ Unique workflow requirements +- ✅ Custom tool integration needed +- ✅ Specific feedback loops required +- ✅ Integration with existing systems +- ✅ Fine-grained control needed + +**When NOT to use:** +- ❌ Standard use cases covered by Skills/Agents +- ❌ Limited development resources +- ❌ Maintenance burden concern +- ❌ Faster time-to-market priority + +**Example use cases:** +- Custom CI/CD integration +- Specialized code analysis pipelines +- Domain-specific automation +- Integration with proprietary systems + +## Decision Rubric + +Use this rubric to determine the right architecture: + +### Task Complexity Analysis + +**Low Complexity** → Direct Prompts +- Single operation +- Clear input/output +- No dependencies +- < 5 steps + +**Medium Complexity** → Skills +- Multiple related operations +- Reusable patterns +- Reference materials helpful +- 5-20 steps + +**High Complexity** → Agents/Subagents +- Multi-step autonomous workflow +- Needs isolated context +- Different tool permissions +- > 20 steps or parallel tasks + +**Custom Complexity** → SDK Primitives +- Unique workflows +- System integration required +- Custom tools needed +- Specific feedback loops + +### Reusability Assessment + +**Single Use** → Direct Prompts +- One-time task +- Project-specific +- No future reuse + +**Team Reuse** → Skills +- Multiple team members benefit +- Common workflows +- Shareable knowledge + +**Organization Reuse** → Skills + Marketplace +- Cross-team benefit +- Standard patterns +- Company-wide knowledge + +**Product Feature** → SDK Primitives +- End-user facing +- Production deployment +- Custom integration + +### Context Management Needs + +**Minimal Context** → Direct Prompts +- Self-contained task +- No external references +- Simple instructions + +**Structured Context** → Skills +- Progressive disclosure needed +- Reference materials required +- Organized information + +**Isolated Context** → Agents/Subagents +- Separate concerns +- Avoid context pollution +- Parallel execution + +**Custom Context** → SDK Primitives +- Specific context handling +- Integration requirements +- Fine-grained control + +### Security & Control Requirements + +**Basic Safety** → Direct Prompts + Skills +- Standard guardrails +- No sensitive operations +- Read-only or low-risk + +**Controlled Access** → Agents with Tool Restrictions +- Specific tool permissions +- Allowlist approach +- Confirmation required + +**High Security** → SDK Primitives + Custom Controls +- Deny-all default +- Explicit confirmations +- Audit logging +- Custom security layers + +## Architecture Patterns + +### Pattern 1: Skills-First Architecture + +**Use when:** Building reusable expertise and workflows + +**Structure:** +``` +Project +├── skills/ +│ ├── domain-expert/ +│ │ ├── SKILL.md +│ │ └── references/ +│ │ ├── patterns.md +│ │ ├── best_practices.md +│ │ └── examples.md +│ └── workflow-automation/ +│ ├── SKILL.md +│ └── scripts/ +│ └── automate.sh +└── .claude/ + └── config +``` + +**Benefits:** +- Reusable across projects +- Progressive disclosure +- Easy to share and maintain +- Clear documentation + +### Pattern 2: Agent-Based Architecture + +**Use when:** Complex autonomous tasks with isolated concerns + +**Structure:** +``` +Main Agent (orchestrator) +├── Explore Agent (codebase analysis) +├── Plan Agent (task planning) +├── Code Agent (implementation) +└── Review Agent (validation) +``` + +**Benefits:** +- Parallel execution +- Isolated contexts +- Specialized expertise +- Clear responsibilities + +### Pattern 3: Hybrid Architecture + +**Use when:** Complex projects with varied requirements + +**Structure:** +``` +Main Conversation +├── Direct Prompts (simple tasks) +├── Skills (reusable expertise) +│ ├── code-review-skill +│ └── testing-skill +└── Subagents (complex workflows) + ├── Explore Agent + └── Plan Agent +``` + +**Benefits:** +- Right tool for each task +- Optimal resource usage +- Flexible and scalable +- Best of all approaches + +### Pattern 4: SDK Custom Architecture + +**Use when:** Unique requirements or product features + +**Structure:** +``` +Custom Agent SDK Implementation +├── Custom Tools +├── Specialized Feedback Loops +├── System Integrations +└── Domain-Specific Workflows +``` + +**Benefits:** +- Full control +- Custom integration +- Unique workflows +- Production-ready + +## Key Principles (2025) + +### 1. Progressive Disclosure +**What:** Show only what's needed, when it's needed. + +**Why:** Avoids context limits, reduces costs, improves performance. + +**How:** Organize skills with task-based navigation, provide query tools, structure information hierarchically. + +### 2. Context as Resource +**What:** Treat context window as precious, limited resource. + +**Why:** Every token counts toward limits and costs. + +**How:** Use progressive disclosure, prefer retrieval over dumping, compress aggressively, reset periodically. + +### 3. Clear Instructions +**What:** Explicit, unambiguous directions. + +**Why:** Claude 4.x responds best to clarity. + +**How:** Be specific, define output format, provide examples, avoid vagueness. + +### 4. Security by Design +**What:** Deny-all default, allowlist approach. + +**Why:** Safe, controlled AI systems. + +**How:** Limit tool access, require confirmations, audit operations, block dangerous commands. + +### 5. Thinking Capabilities +**What:** Leverage Claude's extended thinking mode. + +**Why:** Better results for complex reasoning. + +**How:** Request step-by-step thinking, allow reflection after tool use, guide initial thinking. + +### 6. Two-Message Pattern +**What:** Use meta messages for context without UI clutter. + +**Why:** Clean UX while providing necessary context. + +**How:** Set isMeta: true for system messages, use for skill loading, keep UI focused. + +## Reference Materials + +All architectural patterns, decision frameworks, and examples are in the `references/` directory: + +- **decision_rubric.md** - Comprehensive decision framework +- **architectural_patterns.md** - Detailed pattern catalog +- **best_practices.md** - 2025 Anthropic best practices +- **use_case_examples.md** - Real-world architecture examples + +## Usage Examples + +### Example 1: Determining Architecture for Content Generation + +**Input:** +``` +Using anthropic-architect, I need to build a system that: +- Generates blog posts from product features +- Ensures brand voice consistency +- Includes SEO optimization +- Reusable across marketing team +``` + +**Analysis:** +- Medium complexity (structured workflow) +- High reusability (team-wide) +- Domain expertise needed (content, SEO, brand) +- Progressive disclosure beneficial + +**Recommendation:** **Skills-First Architecture** +- Create `content-generator` skill +- Include brand voice references +- SEO guidelines in references +- Example templates +- Progressive disclosure for different content types + +### Example 2: Code Refactoring Tool + +**Input:** +``` +Using anthropic-architect, I want to: +- Analyze codebase for refactoring opportunities +- Generate refactoring plan +- Execute refactoring with tests +- Review and validate changes +``` + +**Analysis:** +- High complexity (multi-step, autonomous) +- Different contexts needed (explore, plan, code, review) +- Parallel execution beneficial +- Tool permissions vary by stage + +**Recommendation:** **Agent-Based Architecture** +- Main orchestrator agent +- Explore subagent (read-only, codebase analysis) +- Plan subagent (planning, no execution) +- Code subagent (write permissions) +- Review subagent (validation, test execution) + +### Example 3: Simple Code Review + +**Input:** +``` +Using anthropic-architect, I need to: +- Review this PR for bugs +- Check code style +- Suggest improvements +``` + +**Analysis:** +- Low complexity (single operation) +- One-time task +- No reusability needed +- Minimal context + +**Recommendation:** **Direct Prompt** +- Simple, clear instructions +- No skill/agent overhead +- Fast execution +- Sufficient for task + +### Example 4: Custom CI/CD Integration + +**Input:** +``` +Using anthropic-architect, I want to: +- Integrate Claude into CI pipeline +- Custom tool for deployment validation +- Specific workflow for our stack +- Production feature +``` + +**Analysis:** +- Custom complexity +- System integration required +- Production deployment +- Unique workflows + +**Recommendation:** **SDK Primitives** +- Build custom agent with SDK +- Implement custom tools +- Create specialized feedback loops +- Integration with CI system + +## Best Practices Checklist + +When designing your architecture: + +- [ ] Analyzed task complexity accurately +- [ ] Considered reusability requirements +- [ ] Evaluated context management needs +- [ ] Assessed security requirements +- [ ] Applied progressive disclosure where beneficial +- [ ] Chose simplest solution that works +- [ ] Documented architectural decisions +- [ ] Planned for maintenance and updates +- [ ] Considered cost implications +- [ ] Validated with prototype/POC + +## Common Anti-Patterns + +### Anti-Pattern 1: Over-Engineering +**Problem:** Using Agents/SDK for simple tasks + +**Solution:** Start simple, scale complexity as needed + +### Anti-Pattern 2: Context Dumping +**Problem:** Loading entire skills into context + +**Solution:** Use progressive disclosure, query tools + +### Anti-Pattern 3: Mixed Concerns +**Problem:** Single skill/agent doing too much + +**Solution:** Separate concerns, use subagents or multiple skills + +### Anti-Pattern 4: No Security Boundaries +**Problem:** Full tool access for all agents + +**Solution:** Allowlist approach, minimal permissions + +### Anti-Pattern 5: Ignoring Reusability +**Problem:** Recreating same prompts repeatedly + +**Solution:** Extract to skills, share across projects + +## Getting Started + +### Step 1: Describe Your Project +Provide clear requirements, complexity level, and constraints. + +### Step 2: Receive Recommendation +Get tailored architecture with reasoning. + +### Step 3: Review Patterns +Explore similar successful architectures. + +### Step 4: Implement +Follow implementation guidance. + +### Step 5: Iterate +Refine based on results and feedback. + +## Summary + +The Anthropic Architect skill helps you: +- Choose the right primitives for your needs +- Design scalable, maintainable architectures +- Follow 2025 best practices +- Avoid common pitfalls +- Optimize for performance and cost + +**Key Primitives:** +- **Skills** - Reusable domain expertise +- **Agents** - Autonomous complex workflows +- **Prompts** - Simple direct tasks +- **SDK** - Custom integrations + +**Core Principles:** +- Progressive disclosure +- Context as resource +- Security by design +- Clear instructions +- Right tool for the job + +--- + +**"The best architecture is the simplest one that meets your requirements."** diff --git a/skills/anthropic-architect/references/architectural_patterns.md b/skills/anthropic-architect/references/architectural_patterns.md new file mode 100644 index 0000000..82a7f85 --- /dev/null +++ b/skills/anthropic-architect/references/architectural_patterns.md @@ -0,0 +1,965 @@ +# Architectural Patterns + +Comprehensive catalog of proven Anthropic architecture patterns for common use cases. + +## Table of Contents + +1. [Skills-First Patterns](#skills-first-patterns) +2. [Agent-Based Patterns](#agent-based-patterns) +3. [Hybrid Patterns](#hybrid-patterns) +4. [SDK Custom Patterns](#sdk-custom-patterns) +5. [Progressive Disclosure Patterns](#progressive-disclosure-patterns) +6. [Security Patterns](#security-patterns) + +--- + +## Skills-First Patterns + +### Pattern 1: Domain Expert Skill + +**When to use:** +- Specialized domain knowledge needed +- Team-wide expertise sharing +- Consistent application of patterns + +**Structure:** +``` +domain-expert-skill/ +├── SKILL.md +├── references/ +│ ├── core_concepts.md +│ ├── patterns/ +│ │ ├── pattern_1.md +│ │ ├── pattern_2.md +│ │ └── pattern_3.md +│ ├── best_practices.md +│ └── examples/ +│ ├── example_1.md +│ └── example_2.md +└── scripts/ + └── validate.sh +``` + +**Example: Security Expert Skill** +``` +security-expert/ +├── SKILL.md +├── references/ +│ ├── owasp_top_10.md +│ ├── patterns/ +│ │ ├── authentication.md +│ │ ├── authorization.md +│ │ ├── encryption.md +│ │ └── input_validation.md +│ ├── threat_models.md +│ └── examples/ +│ ├── secure_api.md +│ └── secure_storage.md +└── scripts/ + └── security_audit.sh +``` + +**Usage:** +``` +Using the security-expert skill, review this authentication flow +for vulnerabilities following OWASP guidelines. +``` + +**Benefits:** +- Centralized expertise +- Consistent security reviews +- Team knowledge sharing +- Progressive disclosure of security patterns + +--- + +### Pattern 2: Workflow Automation Skill + +**When to use:** +- Repeatable multi-step workflows +- Team-wide process standardization +- Interactive script execution + +**Structure:** +``` +workflow-automation-skill/ +├── SKILL.md +├── workflows/ +│ ├── workflow_1.md +│ ├── workflow_2.md +│ └── workflow_3.md +├── scripts/ +│ ├── step_1.sh +│ ├── step_2.sh +│ └── orchestrate.sh +└── templates/ + ├── template_1.md + └── template_2.md +``` + +**Example: Release Management Skill** +``` +release-management/ +├── SKILL.md +├── workflows/ +│ ├── version_bump.md +│ ├── changelog_generation.md +│ ├── deployment.md +│ └── rollback.md +├── scripts/ +│ ├── bump_version.sh +│ ├── generate_changelog.sh +│ ├── deploy.sh +│ └── release.sh (orchestrator) +└── templates/ + ├── changelog_template.md + └── release_notes.md +``` + +**Usage:** +``` +Using the release-management skill, prepare a new release: +- Bump version to 2.1.0 +- Generate changelog from commits +- Create release notes +``` + +**Benefits:** +- Standardized processes +- Reduced errors +- Faster execution +- Team consistency + +--- + +### Pattern 3: Progressive Disclosure Skill + +**When to use:** +- Large knowledge base +- Context limits are concern +- Query-based information retrieval + +**Structure:** +``` +progressive-skill/ +├── SKILL.md +├── query_tool.sh +├── index.md (high-level navigation) +├── expertise/ +│ ├── by_task/ +│ │ ├── task_1.md +│ │ └── task_2.md +│ ├── by_category/ +│ │ ├── category_1.md +│ │ └── category_2.md +│ └── quick_reference/ +│ └── cheat_sheet.md +└── examples/ + └── contextualized_examples.md +``` + +**Example: API Design Skill** +``` +api-design-expert/ +├── SKILL.md +├── query_expertise.sh +├── index.md +├── expertise/ +│ ├── by_task/ +│ │ ├── rest_api.md +│ │ ├── graphql.md +│ │ └── webhooks.md +│ ├── by_concern/ +│ │ ├── authentication.md +│ │ ├── rate_limiting.md +│ │ ├── versioning.md +│ │ └── documentation.md +│ └── quick_reference/ +│ ├── http_methods.md +│ └── status_codes.md +└── examples/ + └── real_world_apis.md +``` + +**Usage:** +``` +Using api-design-expert, show me best practices for: +- RESTful resource design +- Authentication and authorization +- Rate limiting strategy +``` + +**Query Flow:** +1. Agent loads index.md (high-level) +2. Agent identifies relevant task: "rest_api.md" +3. Skill provides only REST API patterns +4. If auth needed, loads authentication.md +5. Progressive disclosure of information + +**Benefits:** +- Minimal context usage +- Fast responses +- Scalable knowledge base +- Efficient token consumption + +--- + +## Agent-Based Patterns + +### Pattern 4: Multi-Phase Agent Pipeline + +**When to use:** +- Complex workflows with distinct phases +- Different tool permissions per phase +- Isolated contexts beneficial + +**Structure:** +``` +Main Agent (orchestrator) +│ +├── Phase 1: Explore Agent +│ Tools: [Read, Grep, Glob] +│ Context: Codebase exploration +│ Output: Insights, patterns, structure +│ +├── Phase 2: Plan Agent +│ Tools: [TodoWrite] +│ Context: Insights from Phase 1 +│ Output: Detailed plan +│ +├── Phase 3: Execute Agent +│ Tools: [Read, Edit, Write] +│ Context: Plan + target files +│ Output: Code changes +│ +└── Phase 4: Validate Agent + Tools: [Bash, Read] + Context: Changes + tests + Output: Validation results +``` + +**Example: Feature Implementation** +``` +Feature Implementation Pipeline + +1. Explore Agent + - Analyze existing codebase + - Find related code patterns + - Identify integration points + → Output: Architecture analysis + +2. Design Agent + - Review analysis + - Create detailed design + - Plan file changes + → Output: Implementation plan + +3. Code Agent + - Implement feature + - Follow design plan + - Write tests + → Output: Code changes + +4. Review Agent + - Run tests + - Check coverage + - Validate functionality + → Output: Pass/fail + feedback + +5. Main Agent + - Aggregate results + - Report to user + - Handle iterations +``` + +**Usage:** +``` +Implement a new user authentication feature: +1. Analyze current auth system +2. Design JWT-based auth +3. Implement changes +4. Validate with tests +``` + +**Benefits:** +- Clear phase separation +- Minimal permissions per phase +- Isolated contexts (no pollution) +- Parallel execution possible +- Easy to debug and iterate + +--- + +### Pattern 5: Parallel Agent Execution + +**When to use:** +- Independent tasks that can run simultaneously +- Large codebases or datasets +- Time-sensitive operations + +**Structure:** +``` +Coordinator Agent +│ +├─┬─ Worker Agent 1: Task Subset 1 +│ │ +│ ├─ Worker Agent 2: Task Subset 2 +│ │ +│ ├─ Worker Agent 3: Task Subset 3 +│ │ +│ └─ Worker Agent 4: Task Subset 4 +│ +└── Aggregator Agent: Combine Results +``` + +**Example: Codebase Analysis** +``` +Analysis Coordinator +│ +├─┬─ Analyze Agent 1: /src/components/ +│ │ → Component patterns +│ │ +│ ├─ Analyze Agent 2: /src/services/ +│ │ → Service patterns +│ │ +│ ├─ Analyze Agent 3: /src/utils/ +│ │ → Utility patterns +│ │ +│ └─ Analyze Agent 4: /tests/ +│ → Test coverage +│ +└── Aggregator Agent + → Combined analysis report +``` + +**Usage:** +``` +Analyze entire codebase for: +- Code patterns +- Test coverage +- Performance issues +- Security vulnerabilities + +Execute in parallel for speed. +``` + +**Benefits:** +- Massive speedup (4x with 4 agents) +- Independent execution +- Resource optimization +- Scalable to large codebases + +--- + +### Pattern 6: Specialist Agent Team + +**When to use:** +- Different expertise areas needed +- Collaborative task execution +- Review and validation workflows + +**Structure:** +``` +Project Lead Agent (orchestrator) +│ +├── Frontend Specialist Agent +│ Expertise: UI/UX, components, accessibility +│ Tools: Frontend-specific +│ +├── Backend Specialist Agent +│ Expertise: APIs, databases, services +│ Tools: Backend-specific +│ +├── DevOps Specialist Agent +│ Expertise: CI/CD, deployment, infrastructure +│ Tools: DevOps-specific +│ +└── QA Specialist Agent + Expertise: Testing, validation, quality + Tools: Testing-specific +``` + +**Example: Full-Stack Feature** +``` +Feature: Add user profile page + +Project Lead Agent +│ +├── Frontend Agent +│ - Create profile component +│ - Add routing +│ - Implement responsive design +│ Load: frontend-designer skill +│ +├── Backend Agent +│ - Create profile API endpoint +│ - Add database queries +│ - Implement validation +│ Load: api-design-expert skill +│ +├── DevOps Agent +│ - Update deployment config +│ - Add environment variables +│ - Configure monitoring +│ Load: devops-expert skill +│ +└── QA Agent + - Write integration tests + - Validate end-to-end flow + - Check accessibility + Load: qa-test-planner skill +``` + +**Usage:** +``` +Implement user profile feature across the stack: +- Frontend: Profile page with edit capability +- Backend: CRUD API for profile data +- DevOps: Deploy to staging +- QA: Full test coverage +``` + +**Benefits:** +- Specialized expertise +- Parallel execution +- Skills loading per specialist +- Clear ownership +- Comprehensive coverage + +--- + +## Hybrid Patterns + +### Pattern 7: Agents + Skills Hybrid + +**When to use:** +- Complex workflows needing domain expertise +- Reusable knowledge + autonomous execution +- Best of both approaches + +**Structure:** +``` +Agent Workflow +│ +├── Explore Agent +│ Loads: codebase-analysis-skill +│ Expertise: Pattern recognition +│ Tools: [Read, Grep, Glob] +│ +├── Plan Agent +│ Loads: architecture-patterns-skill +│ Expertise: Design patterns +│ Tools: [TodoWrite] +│ +└── Execute Agent + Loads: coding-standards-skill + Expertise: Team conventions + Tools: [Read, Edit, Write] +``` + +**Example: Refactoring Pipeline** +``` +Refactoring Workflow + +1. Analysis Agent + Load: code-quality-skill + - Identify code smells + - Find duplication + - Analyze complexity + Use skill's: anti-patterns reference + +2. Planning Agent + Load: refactoring-patterns-skill + - Choose refactoring patterns + - Plan step-by-step changes + - Estimate risk + Use skill's: safe refactoring strategies + +3. Execution Agent + Load: team-coding-standards-skill + - Apply refactorings + - Follow team style + - Maintain tests + Use skill's: style guide and examples + +4. Validation Agent + Load: testing-strategies-skill + - Run test suite + - Check coverage + - Verify behavior + Use skill's: test validation patterns +``` + +**Usage:** +``` +Refactor the UserService class: +- Load relevant skills for expertise +- Use agents for autonomous execution +- Progressive disclosure of skill knowledge +- Isolated contexts per phase +``` + +**Benefits:** +- Reusable expertise (skills) +- Autonomous execution (agents) +- Progressive disclosure +- Isolated contexts +- Best of both worlds + +--- + +### Pattern 8: Prompts + Skills Fallback + +**When to use:** +- Start simple, escalate complexity +- Most tasks simple, some complex +- Cost optimization + +**Structure:** +``` +Task Router +│ +├── Simple task? → Direct Prompt +│ +├── Needs expertise? → Load Skill +│ └── Still simple? → Skill + Prompt +│ └── Complex? → Skill + Agent +│ +└── Very complex? → Agents + Skills +``` + +**Example: Code Review System** +``` +Code Review Router + +1. Check complexity + - Small PR (< 50 lines)? → Direct Prompt + "Review this PR for basic issues" + + - Medium PR (50-500 lines)? → Load Skill + Using code-review-skill, review this PR + Skill provides: checklist, patterns + + - Large PR (> 500 lines)? → Agent + Skill + Review Agent loads code-review-skill + - Explore codebase context + - Apply review checklist + - Generate comprehensive review +``` + +**Benefits:** +- Cost-effective (simple → cheap) +- Scalable (complex → powerful) +- Flexible (adapts to task) +- Progressive enhancement + +--- + +## SDK Custom Patterns + +### Pattern 9: Custom Tool Integration + +**When to use:** +- Integration with proprietary systems +- Custom tools needed +- Domain-specific operations + +**Structure:** +```typescript +import { Agent, Tool } from 'claude-agent-sdk'; + +// Define custom tool +const customTool: Tool = { + name: 'custom-tool', + description: 'Interacts with proprietary system', + execute: async (params) => { + // Custom implementation + return await proprietarySystem.call(params); + } +}; + +// Create agent with custom tool +const agent = new Agent({ + tools: [customTool, ...standardTools], + systemPrompt: 'You are an expert with custom-system access' +}); +``` + +**Example: CRM Integration Agent** +```typescript +// Custom CRM tools +const getCRMData: Tool = { + name: 'get-crm-data', + description: 'Fetch customer data from CRM', + execute: async ({ customerId }) => { + return await crmAPI.getCustomer(customerId); + } +}; + +const updateCRMData: Tool = { + name: 'update-crm-data', + description: 'Update customer data in CRM', + execute: async ({ customerId, data }) => { + return await crmAPI.updateCustomer(customerId, data); + } +}; + +// Agent with CRM access +const crmAgent = new Agent({ + tools: [getCRMData, updateCRMData], + systemPrompt: `You are a CRM assistant with access to customer data. + Help users query and update customer information.` +}); +``` + +**Usage:** +```typescript +const response = await crmAgent.run({ + task: 'Get customer data for customer ID 12345 and update their email' +}); +``` + +**Benefits:** +- Direct system integration +- Custom business logic +- Proprietary data access +- Fine-grained control + +--- + +### Pattern 10: Custom Feedback Loop + +**When to use:** +- Specific workflow requirements +- Unique validation logic +- Custom iteration patterns + +**Structure:** +```typescript +const customWorkflow = async (task: Task) => { + let result; + let iterations = 0; + const maxIterations = 5; + + while (iterations < maxIterations) { + // Step 1: Generate + result = await agent.generate(task); + + // Step 2: Custom validation + const validation = await customValidator(result); + + // Step 3: Custom decision + if (validation.passed) { + break; // Success + } + + // Step 4: Custom feedback + task = customFeedback(task, validation.issues); + iterations++; + } + + return result; +}; +``` + +**Example: Code Generation with Custom Linter** +```typescript +const codeGenerationWorkflow = async (spec: Specification) => { + let code; + let attempt = 0; + + while (attempt < 3) { + // Generate code + code = await codeAgent.generate(spec); + + // Custom linter validation + const lintResults = await customLinter.check(code); + + if (lintResults.errors.length === 0) { + // Passed linting + break; + } + + // Custom feedback loop + spec = addLintingFeedback(spec, lintResults.errors); + attempt++; + } + + // Custom post-processing + code = await customFormatter.format(code); + + return code; +}; +``` + +**Benefits:** +- Custom validation logic +- Specific iteration patterns +- Business rule enforcement +- Unique workflows + +--- + +## Progressive Disclosure Patterns + +### Pattern 11: Query-Based Disclosure + +**When to use:** +- Large knowledge bases +- Context optimization critical +- Task-specific information needed + +**Structure:** +``` +skill/ +├── SKILL.md (high-level overview) +├── query.sh (interactive query tool) +├── index.md (navigation) +└── content/ + ├── topic_1/ + │ ├── overview.md (loaded first) + │ ├── detailed.md (on demand) + │ └── examples.md (when requested) + └── topic_2/ + ├── overview.md + ├── detailed.md + └── examples.md +``` + +**Query Pattern:** +```bash +# User queries skill +"Using skill, how do I implement authentication?" + +# Skill loading strategy +1. Load: index.md (< 500 tokens) + → Find relevant topic: authentication +2. Load: authentication/overview.md (< 1000 tokens) + → Provides high-level guidance +3. If user needs more: + Load: authentication/detailed.md + → In-depth patterns +4. If user wants examples: + Load: authentication/examples.md + → Real code samples +``` + +**Benefits:** +- Minimal initial context +- Load more as needed +- Efficient token usage +- Fast initial response + +--- + +### Pattern 12: Hierarchical Disclosure + +**When to use:** +- Complex topics with depth +- Progressive learning needed +- Multiple expertise levels + +**Structure:** +``` +skill/ +├── level_1_basics/ +│ └── (fundamental concepts) +├── level_2_intermediate/ +│ └── (common patterns) +├── level_3_advanced/ +│ └── (complex techniques) +└── level_4_expert/ + └── (edge cases, optimization) +``` + +**Disclosure Flow:** +``` +User: "Help me with caching" + +Skill responds: +├─ Level 1: Basic caching concepts +│ User: "I know basics, show me patterns" +│ +├─ Level 2: Common caching patterns +│ User: "Show me advanced optimization" +│ +├─ Level 3: Cache optimization techniques +│ User: "What about distributed caching?" +│ +└─ Level 4: Distributed caching strategies +``` + +**Benefits:** +- Tailored to user expertise +- Prevents overwhelming +- Progressive depth +- Efficient learning + +--- + +## Security Patterns + +### Pattern 13: Allowlist Security Pattern + +**When to use:** +- Sensitive operations +- Controlled tool access +- Security-critical applications + +**Structure:** +```typescript +const secureAgent = new Agent({ + tools: allowlistOnly([ + 'Read', // Safe: read-only + 'Grep', // Safe: read-only + 'Glob', // Safe: read-only + ]), + denylist: [ + 'rm -rf', + 'sudo', + 'curl', // Could leak data + 'wget', // Could leak data + ], + confirmations: [ + 'git push', + 'deployment', + 'data deletion' + ] +}); +``` + +**Example: Production Agent** +```typescript +const productionAgent = new Agent({ + name: 'production-agent', + + // Minimal permissions + tools: [ + 'Read', // View configs + 'Grep', // Search logs + ], + + // Block dangerous operations + denylist: [ + 'rm', + 'delete', + 'drop', + 'truncate', + 'sudo', + 'chmod', + 'exec' + ], + + // Require confirmation + confirmations: [ + 'restart service', + 'change config', + 'modify database' + ], + + // Audit all operations + audit: { + enabled: true, + logLevel: 'verbose', + destination: 'security-log' + } +}); +``` + +**Benefits:** +- Deny-all default +- Explicit permissions +- Confirmations for sensitive ops +- Full audit trail + +--- + +### Pattern 14: Defense in Depth + +**When to use:** +- High security requirements +- Multiple security layers needed +- Critical systems + +**Structure:** +``` +Security Layers: + +Layer 1: Tool Allowlist + → Only approved tools + +Layer 2: Command Validation + → Validate command safety + +Layer 3: Confirmation Required + → Human approval for sensitive ops + +Layer 4: Sandbox Execution + → Isolated environment + +Layer 5: Audit Logging + → Full operation trail + +Layer 6: Rollback Capability + → Undo mechanism +``` + +**Example: Financial System Agent** +```typescript +const financialAgent = new Agent({ + // Layer 1: Tool Allowlist + tools: allowlistOnly(['Read', 'Grep']), + + // Layer 2: Command Validation + preExecute: async (command) => { + return await securityValidator.validate(command); + }, + + // Layer 3: Confirmation Required + confirmations: 'all', + + // Layer 4: Sandbox + sandbox: { + enabled: true, + isolated: true, + networkBlocked: true + }, + + // Layer 5: Audit + audit: { + enabled: true, + level: 'detailed', + retention: '7years', + immutable: true + }, + + // Layer 6: Rollback + rollback: { + enabled: true, + autoSnapshot: true, + quickRevert: true + } +}); +``` + +**Benefits:** +- Multiple security layers +- Defense against various threats +- Compliance ready +- Maximum security + +--- + +## Summary + +Choose patterns based on your requirements: + +**Simple Tasks:** Direct Prompts +**Reusable Expertise:** Skills (Patterns 1-3) +**Complex Workflows:** Agents (Patterns 4-6) +**Best of Both:** Hybrid (Patterns 7-8) +**Custom Needs:** SDK (Patterns 9-10) +**Large Knowledge:** Progressive Disclosure (Patterns 11-12) +**Security Critical:** Security Patterns (Patterns 13-14) + +**Key Principle:** Start simple, add complexity only when needed. diff --git a/skills/anthropic-architect/references/best_practices.md b/skills/anthropic-architect/references/best_practices.md new file mode 100644 index 0000000..2b8bd9f --- /dev/null +++ b/skills/anthropic-architect/references/best_practices.md @@ -0,0 +1,936 @@ +# Anthropic Architecture Best Practices (2025) + +Proven best practices for designing, building, and maintaining Anthropic-based systems. + +## Table of Contents + +1. [Core Design Principles](#core-design-principles) +2. [Progressive Disclosure](#progressive-disclosure) +3. [Context Management](#context-management) +4. [Security & Safety](#security--safety) +5. [Performance Optimization](#performance-optimization) +6. [Skill Design](#skill-design) +7. [Agent Design](#agent-design) +8. [Testing & Validation](#testing--validation) +9. [Maintenance & Evolution](#maintenance--evolution) +10. [Cost Optimization](#cost-optimization) + +--- + +## Core Design Principles + +### 1. Start Simple, Scale Complexity + +**Principle:** Always begin with the simplest solution that meets requirements. + +**Why:** Avoid over-engineering and unnecessary complexity. + +**How:** +``` +Level 1: Try Direct Prompt + └─ Works? → Done + └─ Too complex? → Continue + +Level 2: Create Skill + └─ Works? → Done + └─ Needs isolation? → Continue + +Level 3: Use Agents + └─ Works? → Done + └─ Need custom workflow? → Continue + +Level 4: SDK Primitives + └─ Full control achieved +``` + +**Example:** +``` +Task: Generate code review + +❌ Wrong: Immediately build custom SDK agent +✅ Right: Try direct prompt first + +"Review this PR for: +- Code quality issues +- Security vulnerabilities +- Performance concerns" + +If inconsistent → Create code-review skill +If too complex → Use agent with multiple phases +``` + +--- + +### 2. Progressive Disclosure First + +**Principle:** Show only what's needed, when it's needed. + +**Why:** Optimize context usage, reduce costs, improve performance. + +**How:** +``` +Structure information hierarchically: +├── Index/Overview (always load) +├── Topic Overviews (load on demand) +├── Detailed Content (load when requested) +└── Examples (load if needed) +``` + +**Anti-Pattern:** +```markdown +❌ DON'T: Dump entire skill into context + +skill/ +└── SKILL.md (100KB of everything) + → Context overload + → Slow responses + → High costs +``` + +**Best Practice:** +```markdown +✅ DO: Structure for progressive disclosure + +skill/ +├── SKILL.md (overview, 2KB) +├── index.md (navigation, 1KB) +└── topics/ + ├── topic_1/ + │ ├── overview.md (1KB) + │ └── details.md (loaded on request) + └── topic_2/ + ├── overview.md (1KB) + └── details.md (loaded on request) + +Total initial load: ~4KB vs 100KB +``` + +--- + +### 3. Context as Precious Resource + +**Principle:** Treat every token as valuable and limited. + +**Why:** Context windows have limits and costs. + +**Context Budget:** +``` +Claude 4.x: 200K tokens +- Reserve: 50K for responses +- Available: 150K for context +- Budget wisely! +``` + +**Best Practices:** +- ✅ Load only necessary information +- ✅ Summarize large outputs +- ✅ Use progressive disclosure +- ✅ Reset context periodically +- ✅ Compress repeated information +- ❌ Don't dump raw logs +- ❌ Don't load unused references +- ❌ Don't repeat information + +--- + +### 4. Clear, Explicit Instructions + +**Principle:** Claude 4.x responds best to unambiguous direction. + +**Why:** Reduces errors, improves consistency, better results. + +**Comparison:** +``` +❌ Vague: +"Make the code better" + +✅ Clear: +"Refactor this function to: +1. Extract magic numbers to constants +2. Add type annotations +3. Improve variable names for clarity +4. Add error handling for edge cases +Format: Return only the refactored code" +``` + +**Template:** +``` + +TASK: [Clear task definition] + +REQUIREMENTS: +- [Specific requirement 1] +- [Specific requirement 2] +- [Specific requirement 3] + +OUTPUT FORMAT: +[Exact format expected] + +CONSTRAINTS: +- [Constraint 1] +- [Constraint 2] + + + +[2-3 examples showing desired pattern] + +``` + +--- + +### 5. Security by Design + +**Principle:** Deny-all default, allowlist approach. + +**Why:** Safe, controlled AI systems. + +**Security Checklist:** +- [ ] Minimal tool permissions +- [ ] Allowlist approved tools only +- [ ] Deny dangerous commands +- [ ] Require confirmations for sensitive ops +- [ ] Audit all operations +- [ ] Implement rollback capability +- [ ] Validate all inputs +- [ ] Sandbox execution when possible + +**Default Agent Security:** +```typescript +const secureAgent = new Agent({ + // Deny-all default + tools: [], + + // Explicitly allow minimal tools + allowlist: [ + 'Read', // Read-only + 'Grep', // Search-only + 'Glob' // Find-only + ], + + // Block dangerous operations + denylist: [ + 'rm -rf', + 'sudo', + 'exec', + 'eval' + ], + + // Require confirmation + confirmations: [ + 'git push', + 'deployment', + 'data modification' + ] +}); +``` + +--- + +## Progressive Disclosure + +### Pattern: Query-Based Disclosure + +**Best Practice:** +``` +skill/ +├── SKILL.md +│ Content: High-level overview +│ Size: < 2KB +│ Purpose: Introduce skill capabilities +│ +├── index.md +│ Content: Navigation/TOC +│ Size: < 1KB +│ Purpose: Guide to available topics +│ +└── content/ + └── topic/ + ├── overview.md (load first) + ├── details.md (load on demand) + └── examples.md (load when requested) +``` + +**Loading Strategy:** +``` +1. Initial load: SKILL.md + index.md (~3KB) +2. User asks about "authentication" +3. Load: authentication/overview.md (~1KB) +4. User needs details +5. Load: authentication/details.md (~3KB) +6. User wants examples +7. Load: authentication/examples.md (~2KB) + +Total: 9KB loaded vs 50KB if dumped all at once +Savings: 82% context reduction +``` + +--- + +### Pattern: Hierarchical Expertise + +**Best Practice:** +``` +expertise/ +├── by_task/ +│ ├── authentication.md +│ ├── api_design.md +│ └── testing.md +├── by_language/ +│ ├── typescript.md +│ ├── python.md +│ └── rust.md +├── by_pattern/ +│ ├── repository.md +│ └── factory.md +└── quick_reference/ + └── cheatsheet.md +``` + +**Query Examples:** +``` +"How to implement auth?" → Load: by_task/authentication.md +"TypeScript style guide?" → Load: by_language/typescript.md +"Repository pattern?" → Load: by_pattern/repository.md +"Quick naming conventions?" → Load: quick_reference/cheatsheet.md +``` + +--- + +## Context Management + +### Best Practice 1: Periodic Context Reset + +**Why:** Long sessions accumulate irrelevant context. + +**When to reset:** +- After completing major task +- Context feels "bloated" +- Responses become slower +- Approaching token limits + +**How:** +``` +Option 1: New conversation +- Start fresh conversation +- Provide summary of previous work + +Option 2: Explicit reset request +- Ask Claude to forget irrelevant context +- Summarize key points to retain + +Option 3: Use separate agents +- Different agents for different tasks +- Clean contexts per task +``` + +--- + +### Best Practice 2: Summarize, Don't Dump + +**Anti-Pattern:** +``` +❌ DON'T: Dump raw logs + +"Here are the test results:" +[10,000 lines of test output] +``` + +**Best Practice:** +``` +✅ DO: Summarize key information + +"Test Results Summary: +- Total: 1,247 tests +- Passed: 1,245 (99.8%) +- Failed: 2 + - test_auth_token_expiration (line 456) + - test_rate_limiting (line 789) +- Duration: 2m 34s" +``` + +--- + +### Best Practice 3: Compress Repeated Information + +**Anti-Pattern:** +``` +❌ DON'T: Repeat same information + +Task 1: "Following these coding standards: [full standards]" +Task 2: "Following these coding standards: [full standards]" +Task 3: "Following these coding standards: [full standards]" +``` + +**Best Practice:** +``` +✅ DO: Reference once, use skill + +Task 1: Load: coding-standards-skill +Task 2: "Continue following loaded coding standards" +Task 3: "Continue following loaded coding standards" +``` + +--- + +## Security & Safety + +### Best Practice 1: Minimal Permissions + +**Principle:** Grant minimum tools needed for task. + +**Example: Code Analysis** +```typescript +const analysisAgent = new Agent({ + tools: [ + 'Read', // Read code + 'Grep', // Search code + 'Glob' // Find files + ] + // NO Write, Edit, Bash, etc. +}); +``` + +**Example: Code Modification** +```typescript +const codeAgent = new Agent({ + tools: [ + 'Read', // Read existing code + 'Edit' // Modify code + ] + // NO Bash (can't execute) + // NO full Write (use Edit for safety) +}); +``` + +--- + +### Best Practice 2: Confirmation for Sensitive Operations + +**Always require confirmation:** +- git push +- Deployment commands +- Data deletion +- System modifications +- API calls to production +- Database changes + +**Implementation:** +```typescript +const deployAgent = new Agent({ + confirmations: [ + 'git push', + 'npm publish', + 'kubectl apply', + 'terraform apply', + 'aws', + 'gcloud' + ] +}); +``` + +--- + +### Best Practice 3: Audit Logging + +**Why:** Track all AI operations for security and debugging. + +**What to log:** +- Tool usage +- Commands executed +- Files modified +- API calls made +- Errors encountered +- User confirmations + +**Implementation:** +```typescript +const auditedAgent = new Agent({ + audit: { + enabled: true, + level: 'verbose', + includeContext: true, + destination: './logs/agent-audit.log', + retention: '90days' + } +}); +``` + +--- + +## Performance Optimization + +### Best Practice 1: Parallel Execution + +**When possible, parallelize:** + +**Anti-Pattern:** +``` +❌ Sequential (slow): +1. Analyze file1.ts → 10s +2. Analyze file2.ts → 10s +3. Analyze file3.ts → 10s +Total: 30s +``` + +**Best Practice:** +``` +✅ Parallel (fast): +1. Analyze file1.ts ──┐ +2. Analyze file2.ts ──┼→ All run simultaneously +3. Analyze file3.ts ──┘ +Total: 10s (3x faster) +``` + +**Implementation:** +``` +Launch 3 agents in parallel: +- Agent 1: file1.ts +- Agent 2: file2.ts +- Agent 3: file3.ts +Aggregate results +``` + +--- + +### Best Practice 2: Cache Frequent Queries + +**Pattern:** +``` +skill/ +└── cache/ + ├── frequently_asked.md + └── common_patterns.md +``` + +**Example:** +``` +Common query: "How to handle errors?" + +Instead of processing each time: +1. Maintain: error_handling.md with comprehensive guide +2. Query → Immediately load cached response +3. Fast, consistent responses +``` + +--- + +### Best Practice 3: Optimize Token Usage + +**Token Optimization Checklist:** +- [ ] Use progressive disclosure +- [ ] Summarize large outputs +- [ ] Remove redundant information +- [ ] Compress repeated content +- [ ] Use shorter variable names in examples +- [ ] Remove unnecessary whitespace +- [ ] Reference external docs vs embedding + +**Example:** +``` +❌ High token usage: +const myVeryLongDescriptiveVariableName = 'value'; +const anotherVeryLongDescriptiveVariableName = 'value'; + +✅ Optimized: +const user = 'value'; +const data = 'value'; +// Still clear, fewer tokens +``` + +--- + +## Skill Design + +### Best Practice 1: Single Responsibility + +**Principle:** Each skill should have one clear purpose. + +**Anti-Pattern:** +``` +❌ DON'T: Mega-skill doing everything + +super-skill/ +├── frontend/ +├── backend/ +├── database/ +├── devops/ +└── testing/ +→ Too broad, context overload +``` + +**Best Practice:** +``` +✅ DO: Focused skills + +frontend-expert/ +├── components/ +├── styling/ +└── accessibility/ + +backend-expert/ +├── apis/ +├── services/ +└── databases/ +``` + +--- + +### Best Practice 2: Clear Documentation + +**Skill Documentation Template:** +```markdown +--- +name: skill-name +description: One-sentence description +--- + +# Skill Name + +## What This Skill Does +[2-3 sentences explaining purpose] + +## When to Use +- ✅ Use case 1 +- ✅ Use case 2 +- ❌ Not for use case 3 + +## Quick Start +[Simple example] + +## Reference Materials +- file1.md - Description +- file2.md - Description + +## Examples +[2-3 concrete examples] +``` + +--- + +### Best Practice 3: Version Skills + +**Why:** Track changes, enable rollback, communicate updates. + +**Structure:** +``` +skill/ +├── VERSION (e.g., 2.1.0) +├── CHANGELOG.md +├── SKILL.md +└── references/ +``` + +**CHANGELOG.md:** +```markdown +# Changelog + +## [2.1.0] - 2025-01-15 +### Added +- New pattern: async error handling +- Examples for TypeScript 5.x + +### Changed +- Updated API guidelines for REST + +### Fixed +- Corrected authentication example + +## [2.0.0] - 2024-12-01 +### Breaking Changes +- Restructured reference materials +``` + +--- + +## Agent Design + +### Best Practice 1: Clear Agent Boundaries + +**Principle:** Each agent should have clear, distinct responsibilities. + +**Anti-Pattern:** +``` +❌ DON'T: Monolithic agent doing everything + +BigAgent +├── Explores codebase +├── Plans changes +├── Executes changes +├── Runs tests +├── Deploys +└── Monitors +→ Too much responsibility, hard to debug +``` + +**Best Practice:** +``` +✅ DO: Specialized agents + +Main Orchestrator +├── Explore Agent (read-only) +├── Plan Agent (planning) +├── Code Agent (implementation) +├── Test Agent (validation) +└── Report Agent (aggregation) +``` + +--- + +### Best Practice 2: Agent Communication Patterns + +**Pattern: Parent-Child** +``` +Main Agent +│ +├─→ Subagent 1: Task +│ └─→ Returns: Result +│ +├─→ Subagent 2: Task +│ └─→ Returns: Result +│ +└─→ Main aggregates results +``` + +**Pattern: Pipeline** +``` +Agent 1: Explore + └─→ Output: Analysis + └─→ Agent 2: Plan + └─→ Output: Plan + └─→ Agent 3: Execute + └─→ Output: Changes +``` + +**Pattern: Parallel Workers** +``` +Coordinator +├─┬─ Worker 1 ──┐ +│ ├─ Worker 2 ──┤ +│ ├─ Worker 3 ──┼→ Aggregator → Result +│ └─ Worker 4 ──┘ +``` + +--- + +### Best Practice 3: Error Handling in Agents + +**Principle:** Graceful failure and recovery. + +**Pattern:** +```typescript +const resilientAgent = async (task) => { + try { + const result = await agent.run(task); + return result; + } catch (error) { + // Log error + logger.error('Agent failed', error); + + // Attempt recovery + if (isRecoverable(error)) { + return await retryWithBackoff(agent, task); + } + + // Fallback strategy + return await fallbackStrategy(task); + } +}; +``` + +--- + +## Testing & Validation + +### Best Practice 1: Test Skills + +**What to test:** +- Skill loads correctly +- References are accessible +- Examples are valid +- Scripts execute successfully + +**Example:** +```bash +#!/bin/bash +# test_skill.sh + +echo "Testing skill: $1" + +# Test 1: Skill file exists +if [ ! -f "$1/SKILL.md" ]; then + echo "❌ SKILL.md not found" + exit 1 +fi + +# Test 2: References are valid +for ref in $1/references/*.md; do + if [ ! -f "$ref" ]; then + echo "❌ Reference missing: $ref" + exit 1 + fi +done + +# Test 3: Scripts are executable +for script in $1/scripts/*.sh; do + if [ ! -x "$script" ]; then + echo "❌ Script not executable: $script" + exit 1 + fi +done + +echo "✅ All tests passed" +``` + +--- + +### Best Practice 2: Validate Agent Output + +**Pattern:** +```typescript +const validateAgentOutput = async (output) => { + // Schema validation + if (!matchesSchema(output)) { + throw new Error('Invalid output schema'); + } + + // Business logic validation + if (!meetsRequirements(output)) { + throw new Error('Output doesn\'t meet requirements'); + } + + // Safety checks + if (containsDangerousContent(output)) { + throw new Error('Output contains dangerous content'); + } + + return output; +}; +``` + +--- + +## Maintenance & Evolution + +### Best Practice 1: Regular Skill Updates + +**Schedule:** +- Monthly: Review and update examples +- Quarterly: Major updates for new patterns +- Yearly: Comprehensive review and restructure + +**Update Checklist:** +- [ ] New patterns added +- [ ] Deprecated patterns removed +- [ ] Examples updated for current versions +- [ ] Documentation improved +- [ ] User feedback incorporated +- [ ] Version bumped +- [ ] Changelog updated + +--- + +### Best Practice 2: Deprecation Strategy + +**When deprecating:** +```markdown +## [3.0.0] - 2025-06-01 + +### Deprecated +⚠️ OLD PATTERN (Deprecated, remove in 4.0.0): +[Old pattern example] + +✅ NEW PATTERN (Use instead): +[New pattern example] + +Migration guide: See MIGRATION.md +``` + +**Deprecation Timeline:** +1. Announce deprecation (version N) +2. Maintain both patterns (version N+1) +3. Remove old pattern (version N+2) + +--- + +## Cost Optimization + +### Best Practice 1: Token Efficiency + +**Strategies:** +- Use progressive disclosure (load less) +- Summarize outputs (fewer tokens) +- Cache frequent queries (reuse) +- Compress repeated content (deduplicate) +- Choose smaller models when possible (Haiku vs Sonnet) + +**Example:** +``` +Task: Simple syntax error fix + +❌ Expensive: Use Sonnet for everything +Cost: $X per request + +✅ Optimized: Use Haiku for simple tasks +Cost: $X/5 per request +Savings: 80% +``` + +--- + +### Best Practice 2: Model Selection + +**Choose model based on complexity:** + +**Haiku (Fast, Cheap):** +- Simple queries +- Straightforward tasks +- Well-defined operations +- Cost-sensitive applications + +**Sonnet (Balanced):** +- Medium complexity +- Most general tasks +- Good balance of capability/cost +- Default choice + +**Opus (Powerful, Expensive):** +- Complex reasoning +- Critical tasks +- High-stakes decisions +- Quality over cost + +--- + +## Summary Checklist + +**Design Phase:** +- [ ] Start with simplest solution +- [ ] Apply progressive disclosure +- [ ] Plan for context efficiency +- [ ] Design security boundaries +- [ ] Consider performance needs + +**Implementation Phase:** +- [ ] Follow single responsibility +- [ ] Implement clear documentation +- [ ] Add version control +- [ ] Include error handling +- [ ] Add audit logging + +**Testing Phase:** +- [ ] Test skill loading +- [ ] Validate agent outputs +- [ ] Check security controls +- [ ] Verify performance +- [ ] Test edge cases + +**Maintenance Phase:** +- [ ] Regular updates +- [ ] Deprecation strategy +- [ ] User feedback loop +- [ ] Cost monitoring +- [ ] Performance optimization + +--- + +**Remember:** The best practices evolve. Stay current with Anthropic updates and community patterns. diff --git a/skills/anthropic-architect/references/decision_rubric.md b/skills/anthropic-architect/references/decision_rubric.md new file mode 100644 index 0000000..94ee831 --- /dev/null +++ b/skills/anthropic-architect/references/decision_rubric.md @@ -0,0 +1,821 @@ +# 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:** +```typescript +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:** +```typescript +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:** +```typescript +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:** +```typescript +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:** +```typescript +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:** +```typescript +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:** +```typescript +// 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: +1. **Score** your project on 7 dimensions +2. **Calculate** weighted average +3. **Interpret** score to get recommendation +4. **Validate** with decision tree +5. **Review** example evaluations + +**Key Principle:** Start simple, scale complexity as needed. + +**Remember:** The best architecture is the simplest one that meets your requirements. diff --git a/skills/anthropic-architect/references/use_case_examples.md b/skills/anthropic-architect/references/use_case_examples.md new file mode 100644 index 0000000..0a9f61b --- /dev/null +++ b/skills/anthropic-architect/references/use_case_examples.md @@ -0,0 +1,1000 @@ +# Real-World Use Case Examples + +Comprehensive examples of Anthropic architectures for common use cases, with detailed implementation guidance. + +## Table of Contents + +1. [Code Quality & Review](#code-quality--review) +2. [Feature Development](#feature-development) +3. [Documentation](#documentation) +4. [Testing & QA](#testing--qa) +5. [Refactoring & Modernization](#refactoring--modernization) +6. [Security & Compliance](#security--compliance) +7. [DevOps & Automation](#devops--automation) +8. [Data Analysis](#data-analysis) +9. [Customer Support](#customer-support) +10. [Content Generation](#content-generation) + +--- + +## Code Quality & Review + +### Use Case 1: Automated Code Review System + +**Requirements:** +- Review all PRs automatically +- Check coding standards +- Identify security issues +- Suggest improvements +- Team-wide consistency + +**Complexity Analysis:** +- Task Complexity: 6 (structured workflow) +- Reusability: 8 (organization-wide) +- Context: 5 (needs coding standards) +- Security: 5 (read operations) + +**Recommended Architecture:** **Skills + Direct Prompts** + +**Implementation:** + +**1. Create code-review-expert skill:** +``` +code-review-expert/ +├── SKILL.md +├── references/ +│ ├── coding_standards.md +│ ├── security_patterns.md +│ ├── performance_guidelines.md +│ └── review_checklist.md +└── scripts/ + └── review_pr.sh +``` + +**2. Usage for PRs:** +``` +Simple PR (< 50 lines): + → Direct Prompt + "Using code-review-expert skill, review PR #123" + +Complex PR (> 500 lines): + → Agent + Skill + Review Agent: + - Load code-review-expert skill + - Analyze all changed files + - Generate comprehensive review +``` + +**3. coding_standards.md:** +```markdown +# Team Coding Standards + +## TypeScript +- Use strict mode +- Explicit return types +- No `any` types +- Prefer const over let +- 100 character line limit + +## Patterns +- Repository pattern for data access +- Dependency injection for services +- Factory pattern for object creation + +## Security +- Validate all inputs +- Sanitize user data +- Use parameterized queries +- Never log sensitive data +``` + +**4. Review Workflow:** +```bash +#!/bin/bash +# review_pr.sh + +PR_NUMBER=$1 + +echo "Reviewing PR #$PR_NUMBER..." + +# Get PR diff +gh pr diff $PR_NUMBER > /tmp/pr_diff.txt + +# Review with Claude + skill +claude "Using code-review-expert skill, review this PR: + +Changes: +$(cat /tmp/pr_diff.txt) + +Check for: +1. Coding standards compliance +2. Security vulnerabilities +3. Performance issues +4. Best practices adherence +5. Test coverage + +Format: Provide detailed review with specific line numbers and suggestions." +``` + +**Benefits:** +- Consistent reviews +- Team standards enforced +- Reusable across all PRs +- Fast feedback + +**Metrics:** +- Review time: 2-5 minutes +- Coverage: 100% of PRs +- False positives: < 5% +- Developer satisfaction: High + +--- + +### Use Case 2: Code Quality Dashboard + +**Requirements:** +- Analyze entire codebase +- Track metrics over time +- Identify problem areas +- Generate reports + +**Recommended Architecture:** **Parallel Agents** + +**Implementation:** + +``` +Quality Dashboard Workflow + +Coordinator Agent +│ +├─┬─ Complexity Agent → Analyze code complexity +│ │ +│ ├─ Coverage Agent → Check test coverage +│ │ +│ ├─ Security Agent → Find vulnerabilities +│ │ +│ └─ Duplication Agent → Detect code duplication +│ +└─→ Dashboard Agent → Generate visual report + +All agents run in parallel → 4x faster +``` + +**Code:** +```typescript +// Launch parallel agents +const [ + complexityReport, + coverageReport, + securityReport, + duplicationReport +] = await Promise.all([ + analyzeComplexity(codebase), + analyzeCoverage(codebase), + analyzeSecurity(codebase), + analyzeDuplication(codebase) +]); + +// Aggregate results +const dashboard = generateDashboard({ + complexity: complexityReport, + coverage: coverageReport, + security: securityReport, + duplication: duplicationReport +}); +``` + +--- + +## Feature Development + +### Use Case 3: Full-Stack Feature Implementation + +**Requirements:** +- Implement user authentication +- Frontend + Backend + Database +- Tests and documentation +- Deploy to staging + +**Recommended Architecture:** **Specialist Agent Team + Skills** + +**Implementation:** + +``` +Project Lead Agent +│ +├── Frontend Agent +│ Load: frontend-designer-skill +│ Tasks: +│ - Create login/signup components +│ - Add form validation +│ - Implement token storage +│ - Add loading states +│ +├── Backend Agent +│ Load: api-design-expert-skill +│ Tasks: +│ - Create auth endpoints +│ - Implement JWT generation +│ - Add refresh token logic +│ - Database queries +│ +├── Database Agent +│ Load: database-expert-skill +│ Tasks: +│ - Design user schema +│ - Create migrations +│ - Add indexes +│ - Seed test data +│ +├── Testing Agent +│ Load: testing-strategies-skill +│ Tasks: +│ - Unit tests +│ - Integration tests +│ - E2E tests +│ - Coverage reports +│ +└── DevOps Agent + Load: deployment-expert-skill + Tasks: + - Update configs + - Deploy to staging + - Run smoke tests + - Monitor deployment +``` + +**Execution:** +``` +Phase 1: Planning (Sequential) + Lead Agent creates detailed plan + +Phase 2: Implementation (Parallel) + All specialist agents work simultaneously + - Frontend: 15 minutes + - Backend: 15 minutes + - Database: 10 minutes + - Tests: 20 minutes + Total: 20 minutes (vs 70 minutes sequential) + +Phase 3: Integration (Sequential) + Lead Agent coordinates integration + +Phase 4: Deployment (Sequential) + DevOps Agent deploys to staging +``` + +**Benefits:** +- Parallel execution (70% faster) +- Specialized expertise per layer +- Comprehensive test coverage +- Automated deployment + +--- + +### Use Case 4: Feature Flag System + +**Requirements:** +- Add feature flag capability +- Minimal risk implementation +- Gradual rollout support +- Analytics integration + +**Recommended Architecture:** **Skills + Multi-Phase Agents** + +**Implementation:** + +``` +Phase 1: Exploration Agent + Tools: [Read, Grep, Glob] + Load: architecture-patterns-skill + Task: + - Analyze current architecture + - Identify integration points + - Research feature flag patterns + - Assess risk areas + +Phase 2: Design Agent + Tools: [TodoWrite] + Load: system-design-skill + Task: + - Design feature flag service + - Plan database schema + - Define API contracts + - Create rollout strategy + +Phase 3: Implementation Agent + Tools: [Read, Edit, Write] + Load: coding-standards-skill + Task: + - Implement feature flag service + - Add database migrations + - Create admin UI + - Write documentation + +Phase 4: Testing Agent + Tools: [Bash, Read] + Load: testing-strategies-skill + Task: + - Unit tests + - Integration tests + - Load testing + - Rollback testing + +Phase 5: Deployment Agent + Tools: [Bash] + Load: deployment-patterns-skill + Confirmations: ['deployment', 'database migration'] + Task: + - Deploy to staging + - Run validation tests + - Deploy to production (10% users) + - Monitor metrics +``` + +--- + +## Documentation + +### Use Case 5: API Documentation Generator + +**Requirements:** +- Generate API docs from code +- Include examples +- Keep docs in sync with code +- Multiple output formats + +**Recommended Architecture:** **Skills** + +**Implementation:** + +``` +api-documentation-skill/ +├── SKILL.md +├── references/ +│ ├── openapi_spec.md +│ ├── documentation_guidelines.md +│ └── example_formats.md +├── templates/ +│ ├── endpoint_template.md +│ ├── schema_template.md +│ └── example_template.md +└── scripts/ + └── generate_docs.sh +``` + +**Usage:** +``` +Using api-documentation-skill, generate complete API +documentation for all endpoints in src/api/ + +Include: +- OpenAPI spec +- Request/response examples +- Authentication details +- Error responses +- Rate limiting info + +Format: Markdown with code examples +``` + +**Output:** +```markdown +# User API + +## POST /api/users + +Create a new user account. + +### Request +```json +{ + "email": "user@example.com", + "password": "SecurePass123!", + "name": "John Doe" +} +``` + +### Response (201 Created) +```json +{ + "id": "usr_123", + "email": "user@example.com", + "name": "John Doe", + "createdAt": "2025-01-15T10:30:00Z" +} +``` + +### Errors +- 400: Invalid email format +- 409: Email already exists +- 429: Rate limit exceeded +``` + +--- + +### Use Case 6: Onboarding Documentation + +**Requirements:** +- Help new developers get started +- Multiple learning paths +- Interactive tutorials +- Up-to-date with codebase + +**Recommended Architecture:** **Progressive Disclosure Skill** + +**Implementation:** + +``` +onboarding-guide/ +├── SKILL.md +├── index.md (learning paths) +├── getting_started/ +│ ├── day_1.md +│ ├── day_2.md +│ └── week_1.md +├── by_role/ +│ ├── frontend_dev.md +│ ├── backend_dev.md +│ └── fullstack_dev.md +├── by_topic/ +│ ├── architecture.md +│ ├── deployment.md +│ └── testing.md +└── interactive/ + ├── setup_walkthrough.sh + └── first_pr_guide.sh +``` + +**Progressive Disclosure:** +``` +New developer: "I'm a frontend developer, where do I start?" + +1. Load: index.md + → Shows: Learning paths + +2. Load: by_role/frontend_dev.md + → Shows: Frontend-specific onboarding + +3. Load: getting_started/day_1.md + → Shows: Day 1 tasks + +4. As they progress: + → Load additional topics on demand +``` + +--- + +## Testing & QA + +### Use Case 7: Comprehensive Test Suite Generator + +**Requirements:** +- Generate tests for new features +- Multiple test types +- High coverage targets +- Integration with CI/CD + +**Recommended Architecture:** **Agent + Skills** + +**Implementation:** + +``` +Test Generation Agent +│ +Load Skills: +├── testing-strategies-skill +└── code-analysis-skill + +Workflow: +1. Analyze code to test +2. Identify test scenarios +3. Generate unit tests +4. Generate integration tests +5. Generate E2E tests +6. Verify coverage > 80% +``` + +**Example:** +``` +Using testing-strategies-skill, generate comprehensive test suite +for UserService class: + +Coverage requirements: +- Unit tests: 90%+ +- Integration tests: All API endpoints +- E2E tests: Critical user flows + +Test frameworks: +- Jest for unit/integration +- Playwright for E2E + +Include: +- Happy paths +- Error cases +- Edge cases +- Security tests +``` + +**Generated Output:** +```typescript +// user-service.test.ts +describe('UserService', () => { + describe('createUser', () => { + it('should create user with valid data', async () => { + // Test implementation + }); + + it('should reject invalid email', async () => { + // Test implementation + }); + + it('should reject duplicate email', async () => { + // Test implementation + }); + + it('should hash password', async () => { + // Test implementation + }); + }); + + // ... more tests +}); +``` + +--- + +### Use Case 8: Regression Test Suite Maintenance + +**Requirements:** +- Keep tests up-to-date +- Remove obsolete tests +- Update for API changes +- Improve flaky tests + +**Recommended Architecture:** **Multi-Phase Agents** + +**Implementation:** + +``` +Phase 1: Analysis Agent + - Identify failing tests + - Find flaky tests + - Detect obsolete tests + - Check coverage gaps + +Phase 2: Cleanup Agent + - Remove obsolete tests + - Update outdated assertions + - Fix broken imports + +Phase 3: Enhancement Agent + - Improve flaky tests + - Add missing test cases + - Increase coverage + +Phase 4: Validation Agent + - Run full test suite + - Verify improvements + - Generate report +``` + +--- + +## Refactoring & Modernization + +### Use Case 9: Legacy Code Modernization + +**Requirements:** +- Upgrade from JavaScript to TypeScript +- Update deprecated APIs +- Improve code quality +- Maintain functionality + +**Recommended Architecture:** **Multi-Phase Agents + Skills** + +**Implementation:** + +``` +Modernization Pipeline + +Phase 1: Assessment Agent + Load: code-quality-skill + - Analyze current codebase + - Identify modernization opportunities + - Assess risk levels + - Create priority list + +Phase 2: Planning Agent + Load: refactoring-patterns-skill + - Create detailed migration plan + - Define phases and milestones + - Identify dependencies + - Plan rollback strategy + +Phase 3: TypeScript Migration Agent + Load: typescript-migration-skill + - Convert .js to .ts + - Add type definitions + - Fix type errors + - Update build config + +Phase 4: API Update Agent + Load: api-modernization-skill + - Replace deprecated APIs + - Update to new patterns + - Modernize syntax + - Optimize performance + +Phase 5: Testing Agent + Load: testing-strategies-skill + - Run existing tests + - Add new tests + - Verify functionality + - Check performance + +Phase 6: Validation Agent + - Compare behavior (before/after) + - Run regression tests + - Performance benchmarks + - Generate migration report +``` + +**Safety Measures:** +``` +- Git branch per phase +- Tests after each phase +- Rollback capability +- Progressive rollout +- Monitoring and alerts +``` + +--- + +### Use Case 10: Microservices Extraction + +**Requirements:** +- Extract service from monolith +- Minimal downtime +- Data migration +- Gradual rollout + +**Recommended Architecture:** **SDK Custom Workflow** + +**Implementation:** + +```typescript +const microserviceExtraction = { + phases: [ + { + name: 'Analysis', + agent: analysisAgent, + tasks: [ + 'Identify service boundaries', + 'Map dependencies', + 'Plan data separation', + 'Design API contracts' + ] + }, + { + name: 'Preparation', + agent: prepAgent, + tasks: [ + 'Create new service structure', + 'Set up database', + 'Implement API', + 'Add monitoring' + ] + }, + { + name: 'Migration', + agent: migrationAgent, + confirmations: ['database migration', 'traffic routing'], + tasks: [ + 'Migrate data', + 'Deploy service', + 'Route 10% traffic', + 'Monitor metrics' + ] + }, + { + name: 'Validation', + agent: validationAgent, + tasks: [ + 'Compare responses', + 'Check performance', + 'Verify data consistency', + 'Gradual increase to 100%' + ] + } + ] +}; +``` + +--- + +## Security & Compliance + +### Use Case 11: Security Audit System + +**Requirements:** +- Automated security scans +- OWASP compliance +- Vulnerability detection +- Remediation guidance + +**Recommended Architecture:** **Specialist Agents + Security Skill** + +**Implementation:** +``` +Security Audit Coordinator +│ +├── OWASP Scanner Agent +│ Load: owasp-security-skill +│ Check: OWASP Top 10 vulnerabilities +│ +├── Dependency Scanner Agent +│ Load: dependency-security-skill +│ Check: Vulnerable dependencies +│ +├── Code Scanner Agent +│ Load: secure-coding-skill +│ Check: Code vulnerabilities +│ +├── Config Scanner Agent +│ Load: secure-config-skill +│ Check: Insecure configurations +│ +└── Report Agent + Aggregate: All findings + Prioritize: By severity + Recommend: Remediation steps +``` + +**Security Skill Structure:** +``` +owasp-security-skill/ +├── SKILL.md +├── references/ +│ ├── owasp_top_10_2024.md +│ ├── vulnerability_patterns.md +│ ├── remediation_guides.md +│ └── secure_coding_practices.md +└── checklist/ + ├── injection.md + ├── authentication.md + ├── sensitive_data.md + └── ... +``` + +--- + +## DevOps & Automation + +### Use Case 12: CI/CD Pipeline Generator + +**Requirements:** +- Generate CI/CD pipelines +- Multiple platforms (GitHub, GitLab, etc.) +- Best practices built-in +- Customizable workflows + +**Recommended Architecture:** **Skills** + +**Implementation:** + +``` +cicd-generator-skill/ +├── SKILL.md +├── references/ +│ ├── pipeline_patterns.md +│ ├── best_practices.md +│ └── optimization_tips.md +├── templates/ +│ ├── github_actions/ +│ │ ├── basic.yml +│ │ ├── advanced.yml +│ │ └── monorepo.yml +│ ├── gitlab_ci/ +│ └── jenkins/ +└── scripts/ + └── generate_pipeline.sh +``` + +**Usage:** +``` +Using cicd-generator-skill, generate GitHub Actions pipeline for: + +Project type: Node.js API +Requirements: +- Lint on PR +- Run tests (unit, integration) +- Build Docker image +- Deploy to staging (on main branch) +- Deploy to production (on release tag) +- Security scanning +- Code coverage reports + +Include: +- Caching for faster builds +- Parallel jobs where possible +- Proper secrets management +``` + +**Generated Pipeline:** +```yaml +name: CI/CD Pipeline + +on: + pull_request: + branches: [main] + push: + branches: [main] + tags: ['v*'] + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-node@v3 + with: + node-version: '18' + cache: 'npm' + - run: npm ci + - run: npm run lint + + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-node@v3 + with: + node-version: '18' + cache: 'npm' + - run: npm ci + - run: npm test -- --coverage + - uses: codecov/codecov-action@v3 + + security: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - run: npm audit + - uses: snyk/actions/node@master + + # ... more jobs +``` + +--- + +## Data Analysis + +### Use Case 13: Log Analysis and Insights + +**Requirements:** +- Analyze application logs +- Identify patterns +- Detect anomalies +- Generate insights + +**Recommended Architecture:** **Agents + Progressive Disclosure Skill** + +**Implementation:** + +``` +Log Analysis Pipeline + +1. Collection Agent + - Gather logs from various sources + - Normalize formats + - Filter relevant entries + +2. Pattern Recognition Agent + Load: log-analysis-patterns-skill + - Identify error patterns + - Find performance bottlenecks + - Detect security threats + - Track user behavior + +3. Anomaly Detection Agent + - Compare against baselines + - Flag unusual patterns + - Assess severity + +4. Insights Agent + - Aggregate findings + - Generate recommendations + - Create visualizations + - Prioritize actions +``` + +**Log Analysis Skill:** +``` +log-analysis-patterns-skill/ +├── patterns/ +│ ├── error_patterns.md +│ ├── performance_patterns.md +│ ├── security_patterns.md +│ └── user_behavior_patterns.md +└── insights/ + ├── common_issues.md + └── remediation_steps.md +``` + +--- + +## Content Generation + +### Use Case 14: Technical Blog Post Generator + +**Requirements:** +- Generate blog posts from features +- SEO optimized +- Brand voice consistency +- Code examples included + +**Recommended Architecture:** **Skills** + +**Implementation:** + +``` +technical-blog-generator-skill/ +├── SKILL.md +├── references/ +│ ├── brand_voice.md +│ ├── seo_guidelines.md +│ ├── blog_structure.md +│ └── code_example_formats.md +├── templates/ +│ ├── feature_announcement.md +│ ├── tutorial.md +│ ├── deep_dive.md +│ └── comparison.md +└── examples/ + └── published_posts.md +``` + +**Usage:** +``` +Using technical-blog-generator-skill, create a blog post about +our new API rate limiting feature: + +Target audience: Backend developers +Tone: Technical but accessible +Include: +- Why rate limiting matters +- How to implement +- Code examples (Node.js, Python) +- Best practices +- Common pitfalls + +SEO keywords: API rate limiting, request throttling, API security +``` + +--- + +## Summary + +**Key Patterns by Use Case:** + +| Use Case | Architecture | Why | +|----------|-------------|-----| +| Code Review | Skills + Prompts | Reusable standards, simple workflow | +| Feature Development | Specialist Agents + Skills | Complex, multi-layer, parallel work | +| Documentation | Progressive Disclosure Skill | Large knowledge base, context efficiency | +| Testing | Agents + Skills | Autonomous generation, quality standards | +| Refactoring | Multi-Phase Agents | Complex, risky, needs validation | +| Security | Specialist Agents + Skills | Multiple scan types, expertise needed | +| CI/CD | Skills | Template generation, best practices | +| Data Analysis | Agents + Skills | Pattern recognition, insights | +| Content | Skills | Brand consistency, SEO requirements | + +**Decision Framework:** +1. Analyze your requirements +2. Match to similar use case +3. Adapt architecture pattern +4. Implement and iterate +5. Measure and optimize + +**Remember:** These are starting points. Adapt based on your specific needs and constraints.