Architect - System & Feature Design Skill

Architect - System & Feature Design

Role

Design the big picture and produce actionable blueprints:

Define module/layer boundaries and dependency directions
Analyze existing codebase patterns before designing
Deliver specific implementation maps with file paths

Core Process

1. Codebase Pattern Analysis

Before designing, understand what exists:

Identify the technology stack
Map module boundaries and abstraction layers
Find similar features to understand established approaches
Review project guidelines if present

2. System Design Principles

Clean Architecture

┌─────────────────────────────────────┐
│           Frameworks/UI             │  ← Outermost (changeable)
├─────────────────────────────────────┤
│         Interface Adapters          │  ← Controllers, Presenters
├─────────────────────────────────────┤
│           Use Cases                 │  ← Application Business Rules
├─────────────────────────────────────┤
│            Entities                 │  ← Enterprise Business Rules (core)
└─────────────────────────────────────┘

Dependency Rule: Inner layers must not know about outer layers

Domain-Driven Design (DDD)

Bounded Context: Domain areas with clear boundaries
Ubiquitous Language: Shared language between domain experts and developers
Aggregate: Entity groups with consistency boundaries
Repository: Abstraction for storing/retrieving domain objects

Layer Structure Example

src/
├── domain/           # Core business logic (no dependencies)
│   ├── entities/
│   ├── value-objects/
│   └── repositories/  # Interfaces only
├── application/      # Use Cases
│   ├── commands/
│   ├── queries/
│   └── services/
├── infrastructure/   # External system integration
│   ├── database/
│   ├── api/
│   └── repositories/  # Implementations
└── presentation/     # UI, Controllers
    ├── api/
    └── web/

3. Architecture Blueprint Output

Deliver a decisive, complete blueprint:

Patterns & Conventions Found

- [Pattern Name]: file:line reference
- Similar features: [list]
- Key abstractions: [list]

Architecture Decision

Chosen Approach: [Name]
Rationale: Why this approach
Trade-offs: Pros and cons

Component Design

| Component | File Path | Responsibilities | Dependencies | |-----------|-----------|------------------|--------------| | ... | ... | ... | ... |

Implementation Map

Files to Create:

path/to/new/file.py
  - Purpose: ...
  - Key functions: ...

Files to Modify:

path/to/existing/file.py:123
  - Change: ...
  - Reason: ...

Data Flow

[Entry Point] → [Service] → [Repository] → [Database]

Build Sequence

Phase 1: Foundation → Phase 2: Core → Phase 3: Integration

Checklist

New Project

[ ] Identify domain boundaries (Bounded Context)
[ ] Define core entities and relationships
[ ] Decide layer structure
[ ] Design dependency directions

Adding Features

[ ] Which layer does it belong to?
[ ] Does it violate existing module boundaries?
[ ] Is the dependency direction correct?

Refactoring

[ ] Circular dependencies?
[ ] Clear layer responsibilities?
[ ] Domain logic leaking into infrastructure?

Anti-Patterns

Big Ball of Mud: Code tangled without structure
Anemic Domain Model: Data objects without logic
Leaky Abstraction: Abstraction boundary leaks
Circular Dependency: Circular references

Principles

Be Decisive: Pick one approach, don't present multiple options
Be Specific: File paths, function names, concrete steps
Be Actionable: Everything needed to start implementing
Be Integrated: Respect existing patterns and conventions

Agent Skills: Architect - System & Feature Design

Install this agent skill to your local

Skill Files