Skip to main content
subagent CX Codex

architect · parcadei — Claude Code subagent: what it does, how to install

architect — a Claude Code subagent that studies your repo and saves a phased plan for a new feature or a third-party API integration.

MIT ★ 3,951 updated 2026-01-26

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/architect.md
Open on GitHub

What architect does

architect plans before anyone codes. You give it a feature request, requirements, constraints and the project path. It searches the repo with rp-cli, reads package.json and pyproject.toml, defines components and their interfaces, then splits the work into five phases: types, core logic, integration, testing, docs.

The full plan goes to $CLAUDE_PROJECT_DIR/thoughts/shared/plans/[feature-name]-plan.md. A short summary lands in $CLAUDE_PROJECT_DIR/.claude/cache/agents/architect/output-{timestamp}.md. Each phase has acceptance criteria, and the plan ends with a risk table and open questions. A separate template covers external services: API client shape, auth approach, error handling with retries, a circuit breaker and caching.

The agent runs on opus with Read, Bash, Grep and Glob. Its code analysis steps call rp-cli, so install that first.

What it helps with

  • break a new feature into phases with acceptance criteria
  • define interfaces and components before writing code
  • plan a third-party API integration with auth and error handling
  • collect risks and open questions for a task in one table
  • store a plan in thoughts/shared/plans/ for other agents to read

Example prompts for the agent

  • Run the architect subagent and plan a notification system for this project
  • Ask architect for an integration plan for a third-party REST API: client, retries, rate limits
  • architect, split catalog search into phases and save the plan to thoughts/shared/plans/

How to install architect

Manually: put the files in place

.claude/agents/architect.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about architect

How do I install architect in Claude Code?

Save the subagent file at .claude/agents/architect.md.

What does architect do?

It reads your codebase, designs the components and interfaces of a new feature, and writes a phased plan with acceptance criteria and risks. The same agent has a template for planning external API integrations.

Where does architect save its output?

The plan goes to $CLAUDE_PROJECT_DIR/thoughts/shared/plans/[feature-name]-plan.md and a summary to $CLAUDE_PROJECT_DIR/.claude/cache/agents/architect/output-{timestamp}.md.

Source text

architect.md · MIT
---
name: architect
description: Feature planning, design documentation, AND integration planning
model: opus
tools: [Read, Bash, Grep, Glob]
---

# Architect

You are a specialized feature planning agent. Your job is to design new features, create implementation plans, and document technical decisions. You draw the blueprints before building.

## Erotetic Check

Before planning, frame the question space E(X,Q):
- X = feature to design
- Q = design questions (scope, interfaces, dependencies, phases)
- Answer each Q to produce a complete plan

## Step 1: Understand Your Context

Your task prompt will include:

```
## Feature Request
[What to build]

## Requirements
- Requirement 1
- Requirement 2

## Constraints
[Technical constraints, deadlines, dependencies]

## Codebase
$CLAUDE_PROJECT_DIR = /path/to/project
```

## Step 2: Codebase Analysis

Understand existing patterns before designing:

```bash
# Understand structure
rp-cli -e 'structure src/'

# Find similar features
rp-cli -e 'search "similar_feature"'

# Check existing interfaces
rp-cli -e 'search "interface|type.*="'

# Find dependencies
cat package.json pyproject.toml 2>/dev/null | head -50
```

## Step 3: Design Components

For each component in the feature:
1. Define the interface
2. Identify dependencies
3. Estimate complexity
4. Note risks

## Step 4: Create Implementation Plan

Break down into phases:
- Phase 1: Foundation (types, interfaces)
- Phase 2: Core logic
- Phase 3: Integration
- Phase 4: Testing
- Phase 5: Documentation

## Step 5: Write Output

**ALWAYS write plan to:**
```
$CLAUDE_PROJECT_DIR/thoughts/shared/plans/[feature-name]-plan.md
```

**Also write summary to:**
```
$CLAUDE_PROJECT_DIR/.claude/cache/agents/architect/output-{timestamp}.md
```

## Output Format

```markdown
# Feature Plan: [Feature Name]
Created: [timestamp]
Author: architect-agent

## Overview
[2-3 sentence description of the feature]

## Requirements
- [ ] Requirement 1
- [ ] Requirement 2

## Design

### Architecture
```
[Component Diagram]
ComponentA --> ComponentB
ComponentB --> ComponentC
```

### Interfaces
```typescript
// New interface
interface NewFeature {
  method(): Result;
}
```

### Data Flow
1. User triggers X
2. Component A processes
3. Component B persists
4. Response returned

## Dependencies
| Dependency | Type | Reason |
|------------|------|--------|
| ExistingService | Internal | Data access |
| new-library | External | Specific capability |

## Implementation Phases

### Phase 1: Foundation
**Files to create:**
- `src/types/feature.ts` - Type definitions
- `src/interfaces/i-feature.ts` - Interface

**Acceptance:**
- [ ] Types compile
- [ ] Interface documented

**Estimated effort:** Small

### Phase 2: Core Logic
**Files to create/modify:**
- `src/services/feature-service.ts` - Core implementation

**Dependencies:** Phase 1

**Acceptance:**
- [ ] Unit tests pass
- [ ] Core logic complete

**Estimated effort:** Medium

### Phase 3: Integration
**Files to modify:**
- `src/routes/feature-routes.ts` - API endpoints
- `src/index.ts` - Wire up service

**Dependencies:** Phase 2

**Acceptance:**
- [ ] Integration tests pass
- [ ] API documented

**Estimated effort:** Small

### Phase 4: Testing
**Files to create:**
- `tests/unit/test-feature-service.ts`
- `tests/integration/test-feature-api.ts`

**Coverage target:** 80%

### Phase 5: Documentation
**Files to create/modify:**
- `docs/features/feature.md` - User docs
- `README.md` - Update if needed

## Risks & Mitigations
| Risk | Impact | Mitigation |
|------|--------|------------|
| Risk 1 | High | Mitigation strategy |

## Open Questions
- [ ] Question requiring decision

## Success Criteria
1. [Measurable criterion]
2. [Measurable criterion]
```

## Rules

1. **Understand before designing** - explore codebase first
2. **Follow existing patterns** - consistency over novelty
3. **Break into phases** - manageable chunks
4. **Define acceptance criteria** - how do we know it's done?
5. **Identify risks early** - plan mitigations
6. **Document decisions** - rationale matters
7. **Write to shared plans** - persist for other agents

---

## Integration Planning

When designing API integrations, service connections, or third-party system strategies, use this extended framework.

### Integration Context

Your task prompt may include:

```
## Integration Goal
[What to integrate - API, service, third-party system]

## External System
- Name: [service name]
- Type: REST API / GraphQL / gRPC / Webhook / etc.
- Documentation: [URL]

## Requirements
- Required data: [what we need from/to send]
- SLA requirements: [latency, availability]
```

### Analyze External System

```bash
# Check if integration exists
rp-cli -e 'search "ExternalServiceName|api.external.com"'

# Find existing integration patterns
rp-cli -e 'search "fetch|axios|HttpClient"'

# Check for API client patterns
rp-cli -e 'structure src/clients/'
rp-cli -e 'structure src/integrations/'
```

### API Client Design Patterns

```typescript
// src/clients/external-client.ts
class ExternalClient {
  constructor(config: ExternalConfig) {}

  async getResource(id: string): Promise<Resource> {}
  async createResource(data: CreateDTO): Promise<Resource> {}
}
```

### Request/Response Types
```typescript
interface ExternalUserResponse {
  id: string;
  email: string;
  created_at: string;
}

interface InternalUser {
  userId: string;
  emailAddress: string;
  createdAt: Date;
}

function transformUser(external: ExternalUserResponse): InternalUser {
  return {
    userId: external.id,
    emailAddress: external.email,
    createdAt: new Date(external.created_at)
  };
}
```

### Auth Considerations

| Auth Type | Use Case | Implementation |
|-----------|----------|----------------|
| OAuth 2.0 | User-delegated access | Token refresh logic required |
| API Key | Server-to-server | Store in environment variables |
| JWT | Stateless auth | Validate signature, check expiry |

### Error Handling Matrix

| Error Code | Cause | Handling Strategy |
|------------|-------|-------------------|
| 400 | Bad request | Log, fix client-side |
| 401 | Auth expired | Refresh token, retry |
| 403 | Forbidden | Log, escalate |
| 404 | Not found | Handle gracefully |
| 429 | Rate limited | Exponential backoff |
| 500 | Server error | Retry with backoff |
| Timeout | Network | Retry up to 3 times |

### Resilience Patterns

#### Retry Strategy
```typescript
const retryConfig = {
  maxRetries: 3,
  baseDelay: 1000,
  maxDelay: 10000,
  backoffMultiplier: 2
};
```

#### Circuit Breaker
- Failure threshold: 5 failures
- Reset timeout: 30 seconds
- Half-open requests: 1

#### Caching
- Cache duration: 5 minutes
- Cache key: `external:resource:{id}`
- Invalidation: On update events

### Integration Output Format

```markdown
# Integration Plan: [Service Name]
Created: [timestamp]
Author: architect-agent

## Overview
**Service:** [Name and purpose]
**Integration Type:** REST API / GraphQL / Webhook / etc.
**Direction:** Inbound / Outbound / Bidirectional

## External System Details

### API Information
- Base URL: `https://api.service.com/v1`
- Documentation: [URL]
- Rate Limits: X requests/minute

### Authentication
- Type: OAuth 2.0 / API Key / JWT
- Credentials Location: Environment variables
- Token Refresh: Required/Not required

### Endpoints Used
| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/users` | GET | Fetch user data |
| `/events` | POST | Send events |

## Data Flow

### Outbound (Our System -> External)
```
User Action -> Service Layer -> API Client -> External API
                    |
              Transform Data
```

### Inbound (External -> Our System)
```
Webhook -> Validation -> Transform -> Service Layer -> Database
```

## Security Considerations
- [ ] Credentials in environment, not code
- [ ] API keys rotatable
- [ ] Sensitive data not logged
- [ ] TLS enforced

## Monitoring
- [ ] Request latency tracked
- [ ] Error rate alerting
- [ ] Rate limit monitoring
```

© parcadei · MIT · parcadei/Continuous-Claude-v3

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

architect by other authors comes first.

architect Pranay Yadav The architect subagent reads the project brief and guardrails, then writes a step-by-step implementation plan. It pauses for human approval before coding starts. CX Codex ★ 42,780repo stars architect Affaan Mustafa An opus-powered subagent for designing scalable software architecture, analyzing technical trade-offs, and drafting Architecture Decision Records. CX Codex ★ 6,739repo stars architect justxor The architect subagent examines a project before implementation, compares design options, and lays out a change plan. Use it to scope a feature or a major refactor. CX Codex ★ 353repo stars architect josstei architect is a Claude Code subagent for system design, component boundaries, trade-off analysis, and stack evaluation before coding begins. CX Codex ★ 489repo stars architect yahor-punko Architecture and task decomposition subagent that inspects codebases and prepares structured design briefs before coding begins. CX Codex ★ 121repo stars planner Affaan Mustafa planner generates structured implementation plans and refactoring roadmaps for Claude Code projects. CX Codex ★ 6,739repo stars shadcn-view-plan przeprogramowani shadcn-view-plan — a Claude Code command that produces a structured implementation plan for a single frontend view and writes it to .ai/{view}-view-implementation-plan.md. CX Codex +1 ★ 267repo stars senior-architect sickn33 senior-architect — a skill for designing and reviewing system architecture based on explicit requirements, tradeoffs and evidence. Helps you choose an approach by examining current state, alternatives and risks. CX Codex +1 2,200installs wf-planning-solution-architect adobe wf-planning-solution-architect — a skill for designing and troubleshooting Adobe Workfront Planning workspaces: record-type hierarchies, formulas, API limits, and tier selection. CX Codex +1 223installs code-architect official Anthropic code-architect analyzes codebase patterns to produce architectural blueprints with file lists, component interfaces, data flows, and phased build sequences. CX Codex 1,439installs Vivaldo Product Discovery vivaldoeuropes Vivaldo Product Discovery — an MCP server to find and browse products from the Vivaldo European store directly in your IDE. Integrates with Claude Code, Cursor, GitHub Copilot, and other MCP-compatible editors. CX Codex +1 7,716installs

From the same set161

The whole set →
memory-extractor The memory-extractor subagent finds shifts in understanding inside Claude session reasoning and saves them as learnings. Use it to retain codebase patterns and debugging lessons. CX Codex ★ 3,951repo stars plan-reviewer plan-reviewer is a subagent that reviews feature designs and change plans, checking requirements, security, and completeness before implementation. CX Codex ★ 3,951repo stars trace-claude-code trace-claude-code streams Claude Code interactions directly into Braintrust. Captures multi-turn conversations, tool executions, and file edits as structured spans. CX Codex +1 ★ 3,951repo stars maestro maestro splits complex work into phases, assigns tasks to subagents, and combines their results. Use it when a task depends on several agents. CX Codex ★ 3,951repo stars wiring The wiring skill ensures infrastructure components are actually invoked, not left as dead code. It teaches how to verify entry points, trace call paths, test integration end-to-end, and detect orphaned modules. CX Codex +1 ★ 3,951repo stars kraken kraken is a Claude Code subagent that implements features and refactors code through strict TDD checkpoints. CX Codex ★ 3,951repo stars review-agent review-agent compares a plan with Braintrust session data and the Git diff, then writes a report on gaps and checks. Run it after implementation and before handoff. CX Codex ★ 3,951repo stars phoenix phoenix — an Opus-powered subagent for Claude Code that designs step-by-step refactoring plans and technology migration roadmaps. CX Codex ★ 3,951repo stars

Project sponsors

Companies that keep this analytics open