Agent-Skills.md

Agent Skills: /dev-arch - Architecture Design

Architecture decisions and technical design for features. Use when: (1) New feature requires structural decisions, (2) Validating if current architecture supports requirements, (3) Choosing technology for new capability (payments, real-time, etc.), (4) Greenfield project architecture

UncategorizedID: codihaus/claude-skills/dev-arch

Repository

codihaus/claude-skills
codihaus

Install this agent skill to your local

pnpm dlx add-skill https://github.com/codihaus/claude-skills/tree/HEAD/skills/dev-arch

Skill Files

Browse the full folder contents for dev-arch.

Download Skill

Loading file tree…

skills/dev-arch/SKILL.md

Skill Metadata

Name
dev-arch
Description
Architecture decisions and technical design for features. Use when: (1) New feature requires structural decisions, (2) Validating if current architecture supports requirements, (3) Choosing technology for new capability (payments, real-time, etc.), (4) Greenfield project architecture

/dev-arch - Architecture Design

Skill Awareness: See skills/_registry.md for all available skills.

  • Called by: /debrief (can architecture support this?), /dev-specs (what patterns to use?)
  • Reads: _quality-attributes.md (Architecture Level sections)
  • After: Informs /dev-specs with architecture decisions

Make architecture decisions for features. Ensures scalability, maintainability, and quality from the start.

When to Use

  • New feature that requires structural decisions
  • Existing feature that needs significant changes
  • When /debrief needs to validate feasibility
  • When /dev-specs needs patterns for implementation
  • Technical debt evaluation

Usage

/dev-arch auth                    # Architecture for auth feature
/dev-arch billing --new           # New feature (more thorough)
/dev-arch payments --evaluate     # Evaluate existing architecture

When Called

From /debrief

/debrief creates use cases
    ↓
Calls /dev-arch with question:
    "Can current architecture support these requirements?"
    ↓
/dev-arch returns:
    - Yes, existing patterns work
    - Yes, with minor additions (specify)
    - No, need new architecture (propose)

From /dev-specs

/dev-specs starts generating specs
    ↓
Calls /dev-arch with question:
    "What patterns should specs use?"
    ↓
/dev-arch returns:
    - API patterns (REST/GraphQL, conventions)
    - Data patterns (models, relationships)
    - Component patterns (structure, state)
    - Integration patterns (how pieces connect)

Output

plans/features/{feature}/
├── architecture.md          # Architecture decisions
├── adrs/                    # Architecture Decision Records
│   ├── ADR-001-api-style.md
│   ├── ADR-002-auth-strategy.md
│   └── ...
├── scout.md                 # From /dev-scout
└── specs/                   # From /dev-specs (uses architecture.md)

Expected Outcome

Architecture decisions for what's NEW. Follow existing for what's KNOWN.

Outputs:

  • architecture.md - If architecture decisions made
  • adrs/ADR-*.md - For new decisions only (not for following existing patterns)
  • Patterns to follow (API, data, component, auth)
  • Quality assessment against _quality-attributes.md

Success Criteria

  • Existing patterns followed automatically (no questions asked)
  • Only ask about gaps (missing tech, new requirements)
  • Quality attributes checked (scalability, security, performance, etc.)
  • Team stays in their comfort zone
  • Minimal output for Follow mode, detailed for Design mode

Modes

Auto-detect based on scout:

| Condition | Mode | Behavior | |-----------|------|----------| | Scout has established patterns | Follow | Use existing patterns, no questions, minimal output | | Scout exists but feature needs NEW tech | Extend | Ask ONLY about the gap | | No scout / greenfield OR --new flag | Design | Ask constraint questions, present options |

Context Sources

Read to understand current state:

  • plans/scout/README.md - Project-level patterns
  • plans/features/{feature}/scout.md - Feature-level patterns
  • plans/features/{feature}/README.md - Feature requirements
  • plans/brd/use-cases/{feature}/*.md - Use cases
  • _quality-attributes.md - Architecture Level checklists
  • plans/docs-graph.json - Dependencies

Follow Mode

When: Scout shows established patterns

Approach: Extract and apply automatically

Extract from scout:

  • API style (REST, GraphQL, tRPC)
  • Database (PostgreSQL + Prisma, MySQL, etc.)
  • Frontend (React + Zustand, Vue + Pinia, etc.)
  • Auth (JWT, session, OAuth)
  • Folder structure

Apply to new feature:

  • New endpoints follow existing API pattern
  • New models use existing ORM conventions
  • New components follow existing structure
  • Only flag if requirements CANNOT fit

Output: Minimal architecture.md noting patterns applied

Extend Mode

When: Existing patterns but feature needs something new

Approach: Ask ONLY about the gap

Identify gaps:

  • Feature needs real-time (no WebSocket configured)
  • Feature needs payments (no payment provider)
  • Feature needs file uploads (no storage)
  • Feature needs queue (no background jobs)

Present options for gap only:

  • Recommend based on constraints
  • Pros/cons of each option
  • Ask user to choose

Everything else: Follow existing patterns

Design Mode

When: No existing patterns OR --new flag

Approach: Ask constraint questions, present options

Ask about:

  • Project context (new/existing/rebuild)
  • Team & deployment (solo/small/large, VPS/cloud)
  • Key constraints (tech, budget, timeline, compliance)

Present recommendations based on constraints:

  • Recommended stack with rationale
  • Alternatives considered (why not)
  • Ask user to approve or modify

Gap Analysis

For any mode, identify gaps:

Compare:

  • Requirements (what feature needs)
  • Current capabilities (what exists)
  • Gaps (what's missing)
  • Actions (decisions needed)

Output:

  • Requirements vs Capabilities table
  • Gaps requiring decisions

Decision Making

Only create ADRs for NEW decisions, not for following existing patterns.

Decision categories:

  • API (REST vs GraphQL, versioning, conventions)
  • Data (database, ORM, schema design)
  • Auth (JWT/session/OAuth, permissions)
  • Frontend (state management, component structure)
  • Integration (service connections, event-driven)
  • Infrastructure (caching, queues, storage, email)

Each decision includes:

  • Context (why needed)
  • Options considered (pros/cons/effort)
  • Decision (chosen option + rationale)
  • Consequences (trade-offs accepted)

Quality Assessment

Apply _quality-attributes.md Architecture Level checklists:

  • Scalability: Stateless design, pagination, caching, background jobs
  • Maintainability: Module boundaries, consistent structure, abstracted dependencies
  • Security: Auth strategy, permission model, data encryption
  • Reliability: No single points of failure, graceful degradation
  • Performance: Latency targets, CDN, optimizations
  • Testability: Injectable dependencies, test strategy

Architecture Document

Create plans/features/{feature}/architecture.md with:

  • Overview (high-level description)
  • Architecture diagram (Mermaid)
  • Key decisions table
  • Patterns to follow (API, data, component, auth)
  • Quality checklist
  • ADRs (if created)
  • Risks & mitigations
  • Next steps

ADR Format

Create plans/features/{feature}/adrs/ADR-{NNN}-{slug}.md with:

  • Status (Proposed/Accepted/Deprecated/Superseded)
  • Context (why this decision)
  • Decision (what we're doing)
  • Options considered (with pros/cons)
  • Consequences (positive/negative/neutral)
  • Related decisions

Decision Categories

See references/decision-categories.md for option tables (API, Database, Frontend State, Auth, Infrastructure) and Context7 usage for architecture research.

Categories: API Design, Database, Frontend State, Authentication, Infrastructure.

Tools Used

| Tool | Purpose | |------|---------| | Read | Load requirements, scout, quality attributes | | Write | Create architecture.md, ADRs | | Glob | Find existing patterns | | Grep | Search for conventions | | AskUserQuestion | Clarify decisions | | Context7 | Look up architecture best practices | | WebSearch | Find architecture patterns |

Integration

| Skill | Relationship | |-------|--------------| | /debrief | Calls to validate feasibility | | /dev-scout | Provides current state analysis | | /dev-specs | Consumes architecture decisions | | /utils/diagram | Validates mermaid diagrams | | _quality-attributes.md | Provides checklists |

Key Principle

Use existing patterns. Only ask about what's truly new.

The team's current architecture is their comfort zone. They know it, they control it. Don't suggest microservices to a monolith team. Don't ask about database choice when they're already on PostgreSQL.

Existing patterns → Follow automatically
New requirements that don't fit → Ask only about those
Greenfield → Ask constraint questions

Example Flows

See references/examples.md for detailed Follow/Extend/Design mode examples.

| Mode | Questions Asked | ADRs Created | |------|-----------------|--------------| | Follow | None | None | | Extend | Only for gaps | Only for new decisions | | Design | Full constraint gathering | For all decisions |

Default to Follow mode. Only escalate when necessary.

References

  • references/decision-categories.md - Option tables, Context7 usage
  • references/examples.md - Follow/Extend/Design mode examples