aif-architecture

アーキテクチャ - アーキテクチャガイドラインを生成する

プロジェクトに合わせたアーキテクチャ上の決定事項を含む .ai-factory/ARCHITECTURE.md を生成します。

ワークフロー

ステップ 0：設定とプロジェクトのコンテキストを読み込む

最初に： .ai-factory/config.yaml が存在する場合は読み込み、以下を解決します。

• パス： paths.description と paths.architecture
• 言語： プロンプトには language.ui、生成するアーキテクチャの内容には language.artifacts

/aif から呼び出された場合は、現在のセットアップ実行用に .ai-factory/config.yaml がすでに書き込まれ、language.ui と language.artifacts の値もすでに解決済みであることを前提とします。

config.yaml が存在しない場合は、以下のデフォルト値を使用します。

• DESCRIPTION.md：.ai-factory/DESCRIPTION.md
• ARCHITECTURE.md：.ai-factory/ARCHITECTURE.md
• 言語：en（英語）

次に： .ai-factory/DESCRIPTION.md が存在する場合は（config に指定されたパスを使用して）読み込み、以下を把握します。

• 技術スタック（言語、フレームワーク、データベース、ORM）
• プロジェクトの規模と複雑さ
• 中核となる機能と要件
• 非機能要件

.ai-factory/DESCRIPTION.md が存在しない場合：

⚠️  No project description found.

Run /aif first to set up project context, or describe your project manually:
- What are you building?
- Tech stack (language, framework, database)?
- Team size?
- Expected scale?

単独での使用も可能にし、ユーザーが手動で入力を提供した場合は、その内容を使用します。

.ai-factory/skill-context/aif-architecture/SKILL.md を読み込みます — ファイルが存在する場合は必須です。

このファイルには、パッチ、コードベースの規約、技術スタックの分析から /aif-evolve が蓄積した、プロジェクト固有のルールが含まれています。これらのルールは現在のプロジェクトに合わせたものです。

skill-context ルールの適用方法：

• このスキルの一般的な指示に対するプロジェクトレベルの上書きルールとして扱います
• skill-context のルールが、この SKILL.md に記載された一般ルールと矛盾する場合は、skill-context のルールを優先します（より具体的なコンテキストを優先します。ネストされた CLAUDE.md ファイルと同じ原則です）
• 矛盾がない場合は、SKILL.md の一般ルールと skill-context のプロジェクトルールの両方を適用します
• このプロジェクトの経験からデフォルトが不十分だと判明したために存在するルールなので、スキルのデフォルトと矛盾しているように見えても、skill-context のルールを無視しないでください
• 重要： skill-context のルールは、このスキルのすべての出力に適用されます。ARCHITECTURE.md のテンプレートも対象です。この SKILL.md のテンプレートは基本構成です。skill-context のルールに「アーキテクチャドキュメントには X を必ず含める」または「セクション Y を必ず扱う」とある場合は、それに応じてテンプレートを拡張する必要があります。skill-context のルールに違反する ARCHITECTURE.md を生成するのはバグです。

遵守の確認： 出力成果物を生成した後は、skill-context のすべてのルールに照らして確認してください。違反がある場合は、ユーザーに提示する前に出力を修正してください。

ステップ 1：アーキテクチャの推奨

プロジェクトのコンテキストに基づき、判断マトリクスに照らして評価し、アーキテクチャを推奨します。

$ARGUMENTS でアーキテクチャが指定されている場合（例：/aif-architecture explicit）：

• 直接マッピング（サフィックスは不要）：
  • layers → Layered Architecture
  • microservices → Microservices
  • structured → Structured Modules（バリアントを質問します。以下を参照）
  • explicit → Explicit Architecture（バリアントを質問します。以下を参照）
• レガシーエイリアス（非推奨。現行のパターンにマッピングされます。将来的に削除される可能性があります）：
  • clean → Explicit Architecture
  • ddd → Explicit Architecture
  • monolith → Structured Modules
  • vertical → Explicit Architecture (Vertical Slice By Entity)
• サフィックスあり（バリアントが決まるため、質問は不要です）：
  • structured-layers → Structured Modules (Technical Layer)
  • structured-vertical → Structured Modules (Vertical Slices By Entity)
  • explicit-layers → Explicit Architecture (Technical Layer)
  • explicit-vertical → Explicit Architecture (Vertical Slice By Entity)
  • explicit-flat → Explicit Architecture (Flat Vertical Slice - Simplified)
• サフィックスなし（ユーザーにバリアントを選択してもらいます）：
  • structured がサフィックスなしで指定された場合、ユーザーに次のように質問します："Which folder structure variant do you prefer for Structured Modules? 1. Technical Layer (simpler) or 2. Vertical Slices by Entity (better for large modules)"。成果物を生成する前に、回答を待ちます。
  • explicit がサフィックスなしで指定された場合、ユーザーに次のように質問します："Which folder structure variant do you prefer for Explicit Architecture? 1. Technical Layer or 2. Explicit Architecture (Vertical Slice By Entity) or 3. Explicit Architecture (Flat Vertical Slice - Simplified)"。成果物を生成する前に、回答を待ちます。
• 解決したアーキテクチャをそのまま使用し、推奨ステップをスキップしてステップ 1.5 に進みます。

特定のアーキテクチャが指定されていない場合：

• 判断マトリクス（references/architecture.md を参照）に照らしてプロジェクトを評価します。
• チームの規模、ドメインの複雑さ、スケール要件、技術スタックを考慮します。
• AskUserQuestion を使用して推奨内容を提示します。

Based on your project context:
- [reason 1 from project analysis]
- [reason 2 from project analysis]

Which architecture pattern should we use?

1. [Recommended pattern] (Recommended) — [why it fits]
2. [Alternative 1] — [brief reason]
3. [Alternative 2] — [brief reason]
4. [Alternative 3] — [brief reason]

アーキテクチャの選択肢：

• Structured Modules (Technical Layer)
• Structured Modules (Vertical Slices By Entity)
• Explicit Architecture (Technical Layer)
• Explicit Architecture (Vertical Slice By Entity)
• Explicit Architecture (Flat Vertical Slice - Simplified)
• Microservices
• Layered Architecture （これらのパターンの詳細については references/architecture.md を参照し、推奨内容を作成してください。）

重要な指示： ARCHITECTURE.md 成果物を生成する前に、正確な用語と依存関係の方向を確認するため、必ず references/architecture.md を読んでください。

ステップ 1.5：コードベースとの整合性確認

重要： ドキュメントを生成する前に、選択したアーキテクチャの理想的なフォルダー構成（references/architecture.md を参照）と、既存のコードベースの実際の構成を比較してください。

• プロジェクトが空、またはほぼ一致する場合：ステップ 2 に進みます。
• 大きな不一致がある場合： 理想的なアーキテクチャと整理されていない現状を、黙って統合してはいけません。必ず処理方法をユーザーに確認するため、AskUserQuestion を使用して質問してください。

The current project structure differs significantly from the ideal [Pattern Name] architecture.
[Briefly list 1-2 major differences]

How should we generate the ARCHITECTURE.md?
1. Adapt the guidelines to fit the existing application structure (document reality).
2. Generate the pure, strict architecture guidelines (requires refactoring the application later to match).

ステップ 2 に進む前に、ユーザーの判断を待ちます。

ステップ 2：アーキテクチャ成果物を生成する

必要に応じて、解決されたアーキテクチャパスの親ディレクトリを作成します。

解決されたアーキテクチャ成果物（デフォルト：.ai-factory/ARCHITECTURE.md）を、以下の構成で生成します。プロジェクトの技術スタックと言語に合わせて調整してください。

# Architecture: [Pattern Name]

## Overview
[1-2 paragraphs: what this architecture is and why it was chosen for THIS project]

## Decision Rationale
- **Project type:** [from DESCRIPTION.md]
- **Tech stack:** [language, framework]
- **Key factor:** [primary reason for this choice]

## Folder Structure
\`\`\`
[folder structure adapted to the project's tech stack]
[use actual framework conventions — e.g., Next.js app/ dir, Laravel app/ dir, Go cmd/ dir]
\`\`\`

## Dependency Rules
[What depends on what. Inner vs outer layers. Module boundaries.]

- ✅ [allowed dependency direction]
- ❌ [forbidden dependency direction]

## Layer/Module Communication
[How layers or modules communicate with each other]
- [pattern 1]
- [pattern 2]

## Key Principles
1. [Principle 1 — adapted to this project]
2. [Principle 2]
3. [Principle 3]

[If the user chose Option 2 (strict architecture) in Step 1.5, add the following section:]
## Legacy vs New Code Policy
- **New Features:** All new code MUST strictly follow the architecture defined in this document.
- **Legacy Code Modification:** Do NOT automatically refactor unrelated legacy code to fit this architecture. Touch legacy code only when necessary for bug fixes, when tasked with explicit refactoring, or when adapting it to be consumed by new features.
- **Interoperability:** When new code must call legacy code, isolate the interaction using adapters, interfaces, or facades so that legacy patterns do not pollute the new architecture.

[If the user chose Option 1 (adapt to reality) in Step 1.5, add the following lighter section:]
## Code Organization Note
- **New Features:** All new code should follow the architecture defined in this document where practical.
- **Existing Code:** Document the current structure as-is. When modifying existing code, prefer following the architectural conventions in this document, but do not force a rewrite of unrelated code.
- **Interoperability:** When new code must call existing code, prefer clean interfaces but do not refactor purely for structural alignment.

## Code Examples

### [Example 1 title]
\`\`\`[language]
[code example in the project's language/framework]
\`\`\`

### [Example 2 title]
\`\`\`[language]
[code example showing dependency rule]
\`\`\`

## Anti-Patterns
- ❌ [What NOT to do in this architecture]
- ❌ [Common mistake to avoid]

生成ルール：

• すべての例をプロジェクトの言語とフレームワークに合わせて調整します（Go プロジェクトに TypeScript の例を使わないでください）
• プロジェクトで実際に使われている規約（インポートパス、命名規則など）を使用します
• 実用性を重視し、日々の開発に影響するルールに焦点を当てます
• 生成するフォルダー構成は、ステップ 1.5 でのユーザーの判断（実情に合わせて調整するか、厳密に純粋なアーキテクチャにするか）に基づいて作成します。ユーザーの同意なく自動的に統合しないでください。

ステップ 3：DESCRIPTION.md を更新する

解決された DESCRIPTION.md のパスが存在する場合、解決された language.artifacts にアーキテクチャ参照セクションを追加または更新します。 デフォルトのパスを直接指定せず、設定から解決されたアーキテクチャパスを使用します。

## [Localized heading: Architecture]
[Localized sentence in resolved artifacts language referencing the resolved architecture artifact path for detailed architecture guidelines.]
[Localized label: Pattern]: [chosen pattern name]

ステップ 4：AGENTS.md を更新する

プロジェクトのルートに AGENTS.md が存在する場合、解決された language.artifacts でローカライズされた「AI Context Files」テーブルに、解決されたアーキテクチャ成果物のパスを追加します。

| [resolved-architecture-path] | [Localized architecture artifact description in resolved artifacts language] |

解決されたアーキテクチャパスがすでに存在しない場合にのみ追加します。

ステップ 5：確認する

解決された language.ui で確認を提示し、解決されたアーキテクチャパスを報告します。

[Localized success heading in `language.ui`]

[Localized pattern label in `language.ui`]: [chosen pattern]
[Localized file label in `language.ui`]: [resolved architecture path]

[Localized key-rules heading in `language.ui`]:
- [rule 1]
- [rule 2]
- [rule 3]

[Localized closing sentence in `language.ui` about workflow skills following these architecture guidelines.]

成果物の所有権

• 主な所有対象：解決されたアーキテクチャ成果物のパス（デフォルト：.ai-factory/ARCHITECTURE.md）。
• 設定による上書きを尊重します：config.yaml で指定されている場合は、そこから解決されたアーキテクチャパスに書き込みます。
• 許可される関連更新：解決された DESCRIPTION パス（config.yaml から取得）にあるアーキテクチャ参照、および AGENTS.md のコンテキストテーブルにあるアーキテクチャ行。
• 読み取り専用のコンテキスト：ロードマップ、ルール、調査、計画の成果物。ただし、ユーザーが明示的に別の操作を求めた場合を除きます。

---