Clean Architecture Methodology

Core Principle (CRITICAL)

Agents do not explore outside Allowed Paths. "Just in case grep the whole thing" is PROHIBITED. If needed, request PM for Allowed Paths expansion.

Rules

1. Reference Restriction: Do not read files outside Context Package
2. Contract Read-Only: ALL agents cannot modify contracts (proposals only)
3. Dependency Direction: Domain <- Usecase <- Interface <- Infra

MEMO.md Access

Layer-Specific Context Packages

Domain Layer:

• docs/contracts/dtos.md, docs/layers/domain/*
• src/domain/**, tests/unit/domain/**

Usecase Layer:

• docs/contracts/ports.md, docs/contracts/dtos.md, docs/layers/usecase/*
• src/usecase/**, tests/unit/usecase/**
• src/domain/** (dependency reference only)

Interface Layer:

• docs/contracts/api.md, docs/contracts/dtos.md, docs/layers/interface/*
• src/interface/**, tests/unit/interface/**
• src/usecase/** (dependency reference only)

Infra Layer:

• docs/contracts/ports.md, docs/layers/infra/*
• src/infra/**, tests/unit/infra/**

Role-Based Operation Modes

Sub-Agent概念をスキルとして運用。場面に応じてClaudeが適切なモードに切り替える。

Planner Mode

When: 複雑な機能の実装計画が必要な時 Principle: Planning is docs-based - NO src access by default

Process:

1. Requirements analysis (目的、成功条件、前提条件の明確化)
2. Architecture review (docs/contracts/* + docs/layers/[target]/* を参照)
3. Step breakdown (具体的なアクション、ファイルパス、依存関係、リスク)
4. Implementation order (依存順に優先、関連変更をグループ化)

Output format:

# Implementation Plan: [Feature Name]
## Overview / Requirements / Architecture Changes
## Implementation Steps (Phase 1, 2, ...)
## Testing Strategy / Risks & Mitigations / Success Criteria

Architect Mode

When: アーキテクチャ判断、システム設計が必要な時 Principle: docs-based design; PM must grant Allowed Exception: src/[path]/** for src access

Process:

1. Current state analysis (既存アーキテクチャ、技術的負債)
2. Requirements gathering (機能/非機能要件、統合ポイント)
3. Design proposal (コンポーネント図、データモデル、API契約)
4. Trade-off analysis (各判断のPros/Cons/Alternatives/Decision)

Architecture Decision Records (ADR):

## ADR-XXX: [Title]
- Status: proposed/accepted/deprecated
- Context: [Why this decision is needed]
- Decision: [What was decided]
- Consequences: [What changes as a result]

Refactor Mode

When: デッドコード削除、コード整理が必要な時

Process:

1. Analysis (検出ツールで未使用コード/依存を特定)
2. Categorize by risk (SAFE: unused exports → MEDIUM: shared utilities → HIGH: core logic)
3. Remove in dependency order (leaf nodes first)
4. Verify after each removal (tests still pass)
5. Document in DELETION_LOG.md

Documentation Mode

When: ドキュメント更新が必要な時 Access: Read all files, Write only docs/**, README.md, CLAUDE.md

Process:

1. Repository structure analysis
2. Compare docs with actual code state
3. Update outdated sections
4. Generate codemaps/dependency graphs if needed

PM (Project Manager) Guide

PMはユーザーと直接つながるセッション。サブエージェント統合・契約管理・Context Package配布を担当。

PM の5つの責務

1. Context Package配布: サブエージェント起動時に Allowed Paths を明示
2. 契約管理: contracts/* の変更提案を受け、承認/却下を判断
3. MEMO.md統合: 各レイヤのMEMO.mdを読み、全体整合性を確認
4. 例外付与: architect等が src アクセスを要求した場合の判断
5. Git追跡: コード変更の節目でcommit & push

Agent Activation Template (Task tool用)

[ROLE] を起動。
Layer: <domain|usecase|interface|infra>
Allowed Paths:
- docs/contracts/*
- docs/layers/[layer]/*
- src/[layer]/**
- tests/unit/[layer]/**
Goal: [具体的なタスク]
Done: [完了条件]

PM専用アクセス権

Workflows

Requirements Definition Flow

ユーザーがアイデアや要件を語り始めた時に自動起動。

あなたは「要件定義コーチ」として振る舞う:

1. ユーザーのアイデアを要約して確認（3-6行）
2. 最重要の不確定点から順に質問（最大5問、選択肢付き）
3. 仕様書の叩き台を作成（以下のフォーマット）
4. 各ターンで「決まったこと/未確定」を整理

Requirements Document Format:

1. 概要 / 2. 想定ユーザー / 3. ユースケース一覧
2. 主要ユーザーフロー（攻略本形式）
3. 機能要件（Must/Should/Could）
4. 権限とアカウント / 7. 通知・履歴・検索
5. エラーハンドリング方針 / 9. 非機能要件
6. 用語集 / 11. スコープ外 / 12. Assumptions & Questions

制約: 設計しない（DB/API/モジュール/クラス/技術選定は書かない）。ユーザー視点の仕様のみ確定。

Feature Development Flow

1. Planner Mode (対象レイヤ) → 設計ドキュメント作成
2. Architect Mode           → 契約整合性確認、提案検討
3. [PMが契約変更を承認]
4. /tdd-guide              → テスト作成 → 実装
5. /build-resolver         → (ビルドエラー時のみ)
6. /code-review-excellence → コードレビュー
7. /security-review        → (リリース前)
8. Documentation Mode      → ドキュメント更新

Change Management Flow

仕様変更/修正依頼時に起動。順序: 契約→受け入れ条件→設計→実装→監査/QA

1. Impact Analysis: 影響する契約・レイヤ・テスト・リスクを箇条書き
2. Contract判定: 契約変更 yes/no。yesなら差分案を先に提示しPMが更新
3. Design Update: 対象レイヤのDESIGN.md更新（Planner Mode）
4. Implementation: /tdd-guide でテスト→実装（Allowed Paths明示）
5. Audit: /code-review-excellence → /security-review → Documentation Mode

Major Rework Flow

大規模リワーク（構造変更）時。段階移行で進行。

Phase 0: Freeze - 現行の契約・受け入れ条件・主要フローを整理。回帰テスト追加 Phase 1: New Contract - 新旧契約を共存。v2用DESIGN.md更新。互換アダプタ方針決定 Phase 2: Migration - レイヤ単位に実装（domain→usecase→interface→infra）。旧新並行稼働 Phase 3: Cutover - 新経路へ完全切替。旧コード/契約削除。Refactor Mode + Documentation Mode

Contract System

Contract File Structure

docs/contracts/
├── dtos.md       # Data Transfer Objects (全レイヤ共通)
├── ports.md      # Ports/Interfaces (Domain↔Infra)
├── api.md        # API Contracts (Interface layer)
└── events.md     # Domain Events (optional)

DTO Naming: {Operation}{TargetDomain}{Role}

• Suffixes: Input, Output, Request, Response, Query, Params
• Format: YAML with field definitions + validation constraints

Port Naming: {TargetDomain}{Category}Port

• Categories: RepositoryPort, GatewayPort, NotifierPort
• Format: YAML with method signatures + error codes

Contract Change Principles

1. Backward compatibility: Do not break existing contracts
2. Minimal change: Only change what's necessary
3. Impact evaluation: Clarify affected scope before changing
4. Gradual migration: Large changes use deprecation → migration → removal

Skill Integration

Prohibited Actions (All Agents)

• Grep/glob on entire codebase
• Reading files outside Context Package
• Reading other agent's MEMO.md (except PM)
• Modifying contracts directly (proposals only)
• Bypassing dependency direction rules