Agent-Skills.md

Agent Skills: Architect - System & Feature Design

아키텍처, 설계, 시스템 설계, 구조 설계, 레이어 설계, 블루프린트, 컴포넌트 설계 - Use when designing systems, layer structures, module boundaries, or feature architectures. Provides both high-level system design (Clean Architecture, DDD) and actionable implementation blueprints.

UncategorizedID: aimskr/aims-toolkit/architect

Repository

aimskr/aims-toolkit
aimskr

Install this agent skill to your local

pnpm dlx add-skill https://github.com/aimskr/aims-claude-toolkit/tree/HEAD/skills/architect

Skill Files

Browse the full folder contents for architect.

Download Skill

Loading file tree…

skills/architect/SKILL.md

Skill Metadata

Name
architect
Description
"아키텍처, 설계, 시스템 설계, 구조 설계, 레이어 설계, 블루프린트, 컴포넌트 설계 - Design systems, layer structures, module boundaries, and feature architectures. Outputs actionable blueprints with file paths. Use when planning architecture for new features or restructuring existing systems. Do NOT use for code implementation (use feature-development) or code-level refactoring (use refactor-cleaner)."

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

Architecture Challenge (Devil's Advocate)

결정된 아키텍처에 대해 반드시 아래 3가지를 점검:

  1. 전제 공격: 이 아키텍처가 전제하는 가정 중 틀릴 수 있는 것은? (1-2문장)
  2. 반례: 이 패턴이 실패하거나 부적합했던 알려진 사례는? (1-2문장)
  3. 대안 인지: 같은 문제를 완전히 다른 방식으로 해결하는 접근은? (1-2문장)

아키텍처를 뒤집는 것이 목적이 아님. 사용자가 약점을 인지한 상태에서 확정하도록 돕는 것. 사용자에게 Challenge 결과를 공유하고, "이 약점을 감수하고 진행할까요?" 확인 후 다음 단계로.

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

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

Completion

블루프린트(Component Design + Implementation Map + Build Sequence)가 사용자에게 전달되고 승인되면 완료.

Troubleshooting

Design feels too abstract: Start from codebase analysis (Phase 1). Ground design in existing patterns before introducing new ones. Multiple valid approaches with no clear winner: Apply constraints — which approach requires fewer new abstractions? Which has the smallest blast radius? User wants architecture but scope is unclear: Ask for 2-3 concrete use cases. Design for those, note extensibility points for future needs.