---
title: 出力ディレクトリ構造
description: NexusArchitectが使うreports/とwork/のディレクトリ構造、フォルダ・ファイルそれぞれの役割について詳しく説明します
seo:
  image: /ogp.png
---

NexusArchitectは、次のディレクトリ構造を使います(存在しない場合は、`init-output`系のSkillが作成します)。

<FileTree>
- reports/ 企画・設計・レビューの成果物
- work/ 進捗・トレーサビリティ・コストの記録
- generated/ 実際に動くコード
- design-system/ デザインシステム
</FileTree>

`reports/`が唯一の真実源(single source of truth)であるのに対して、`work/`はパイプラインの状態を記録するファイル群です。`generated/`(フロントエンド/バックエンド/インフラのコード)と`design-system/`(トークン・コンポーネント一覧)は、`reports/`とは別に管理されます。

<Panel title="reports/の中身は「どこから始めたか」で変わります">
NexusArchitectには`reports/`を書き込む入り口が3つあります。**同じ番号のフォルダでも、どの入り口を使ったかで意味が変わる**ので、まずこの前提を押さえてください。

1. **`/product:start`から始める(最も一般的)** — Visionからアーキテクチャまでを企画する`product`パイプライン。`reports/00_core/`〜`reports/05_adaptation/`、`reports/report/`を使います。多くのプロジェクトは、このあと`export-backlog`で`reports/backlog/`に引き渡します。
2. **`architect`を新規開発の起点として直接使う(グリーンフィールド経路)** — 企画を経ずに、要件定義からアーキテクチャ設計・実装仕様まで進める経路。`reports/00_requirements/`、`reports/03_design/`、`reports/06_implementation/`などを使います。
3. **`architect`を既存システムの改修の起点として使う(レガシー経路)** — 既存コードを調査・評価し直す経路。`reports/before/`、`reports/01_analysis/`、`reports/02_evaluation/`などを使います。

このページでは、この順番([1] product起点 → 共通の`backlog/`と`work/` → [2][3] architect単独起点)で説明します。
</Panel>

<Panel title="reports/をブラウザで読みたい場合">
`tools/docs-site.sh`は、`reports/`をそのまま[Blume](https://useblume.dev)でローカルの検索可能なドキュメントサイトにするツールです。レポート1件=1ページで、Mermaid図もレンダリングされ、OpenAPI/AsyncAPI仕様はAPIリファレンスとして、`full-report.html`はそのまま表示されます。`reports/`自体は書き換えず、`sync`/`dev`/`build`/`preview`/`validate`/`clean`のサブコマンドを持ちます。
</Panel>

## 1. productパイプラインの出力(`reports/00_core/` 〜 `reports/report/`)

`/product:start`で作られる、番号付きフォルダです。フォルダの番号はフェーズの順序をそのまま表しています。

<FileTree>
- reports/
  - 00_core/ Vision, Scope, Success Metrics, Revenue Model, Assumptions
  - 01_ux/ Persona, Journey, Positioning, Domain Stories
  - 02_spec/ UI Mocks, Feature List, Data Model
  - 03_domain/ Bounded Contexts, API Design, Architecture, Tech Fitness
  - 04_quality/ SLA, NFR
  - 05_adaptation/ adapt-changeの出力(オンデマンド)
  - report/ 統合HTMLレポート、レビュー結果
</FileTree>

### `00_core/` — 事業の方向性

| ファイル | 発行するSkill | 内容 |
|---|---|---|
| `vision-mission-value.md` | `define-vision` | Vision/Mission/Valueをまとめた図(Vision Board) |
| `pr-faq.md` | `define-vision` | Amazon Working Backwards形式のPR-FAQ(想定プレスリリース+Q&A) |
| `success-metrics.md` | `define-success-metrics` | North Star Metric、それを支える入力指標3〜5件、ガードレール指標 |
| `market-landscape.md` | `research-landscape`(任意) | TAM/SAM/SOM、競合マトリクス、Kano分類、PoD/PoP戦略 |
| `revenue-model.md` | `design-revenue` | Lean Canvas、収益モデル |
| `benefit-evaluation.md` | `design-revenue` | LTV/CAC等、再計算可能なユニットエコノミクスのテンプレート |
| `constraints.md` | `define-scope` | 制約の分類 |
| `scope-definition.md` | `define-scope` | MoSCoW、RICEスコアによるスコープ定義 |
| `product-name.md` | `name-product`(任意) | 頭字語プロダクト名の候補と、Visionの言葉から逆算した根拠 |
| `assumptions.md` | `validate-assumptions`(検証ゲート) | 崩壊インパクトが大きい順に並べた仮説リスト |
| `validation-plan.md` | `validate-assumptions`(検証ゲート) | 各仮説の検証方法・キル閾値と、Go/No-Go判定 |

`assumptions.md`と`validation-plan.md`を書く`validate-assumptions`は、[検証ゲート](/concepts/validation-gate)そのものです。判定結果自体は`work/pipeline-progress.json`の`gates`にも記録されます。

### `01_ux/` — 誰がどう使うか

| ファイル | 発行するSkill | 内容 |
|---|---|---|
| `personas.md` | `generate-persona` | JTBDペルソナ、proto-persona |
| `journey-maps.md` | `map-journey` | ステージ×レイヤーのジャーニーマップ、Moment of Truth |
| `positioning.md` | `design-positioning` | Dunford 5要素、Hookモデル、タッチポイントマトリクス |
| `domain-stories/domain-story-{slug}.md` | `create-domain-story`(任意) | Domain Storytelling。後続の`generate-ui-mock`が読む画面フローの骨格になる |

### `02_spec/` — 実装できる粒度の仕様

| ファイル | 発行するSkill | 内容 |
|---|---|---|
| `ui-mocks/` | `generate-ui-mock` | クリックで画面が切り替わる、単体で動くHTMLのセット |
| `feature-list.md` | `define-features` | 画面上の操作をCommandに変換した機能一覧、MoSCoW、User Story Map(ジャーニー×MoSCoWの別視点) |
| `data-model.md` | `define-data-model` | 2段階(明示的+CRUDマトリクスからの暗黙的)で抽出したエンティティ |

任意で実行する`generate-frontend`は、ここまでの出力を材料に`generated/frontend/`(このフォルダの外)へReact/Storybookの実装を生成します。

### `03_domain/` — ドメインの分割とAPI設計

| ファイル | 発行するSkill | 内容 |
|---|---|---|
| `domain-map.md` | `map-domains` | Core/Supporting/Genericのサブドメイン分類 |
| `bounded-contexts.md` | `map-domains` | 境界コンテキストの定義とコンテキストマップ |
| `ubiquitous-language.md` | `map-domains` | ドメイン語彙の日英対応表(後で`shared-context/`にも反映される) |
| `api-design.md` | `design-api` | System/Process/Experienceという3階層でのAPI設計 |
| `architecture.md` | `design-architecture`(統合フェーズ) | ランタイム図、クリティカルパスのシーケンス、デプロイメント図 |
| `tech-stack-fitness.md` | `design-architecture`(統合フェーズ) | Kong/ScalarDB/ScalarDB Analytics/ScalarDB Saga/ScalarDLの技術適合性評価 |

### `04_quality/` — 品質要件

| ファイル | 発行するSkill | 内容 |
|---|---|---|
| `sla.md` | `design-sla` | SLI/SLO/SLA、エラーバジェット、クリティカリティ階層 |
| `nfr.md` | `define-nfr` | SLOから導出した、測定可能なNFR |

### `05_adaptation/` — 変更の反映(オンデマンド)

| ファイル | 発行するSkill | 内容 |
|---|---|---|
| `change-log.md` | `adapt-change` | 何が、なぜ変わったかの記録 |
| `impact-analysis.md` | `adapt-change` | `work/traceability.json`から計算した影響範囲(再実行すべきフェーズ)の分析 |

`adapt-change`は他のフェーズのように順番待ちせず、市場の変化や制約の変更が起きたときに単独で実行します。

### `report/` — レビューと統合レポート(Phase R)

| ファイル | 発行するSkill | 内容 |
|---|---|---|
| `review.md` | `review`(任意) | Consistency/Traceability/Extensibility/Strategyという4視点でのレビュー結果 |
| `full-report.html` | `report`(任意) | 「重要な仮説と検証状況」を先頭に置いた、自己完結型の統合HTMLレポート |

## 2. `reports/backlog/` — バックログ運用の出力

`export-backlog` → `implement-backlog` → `review-issue` → `merge-issue`という、実際のプロジェクトで最もよく使われる4スキル([バックログ運用](/skills/backlog/export))が書き込むフォルダです。`reports/`の番号付きフォルダ(product側)がどんな入り口で作られたものでも、ここには関係なく取り込めます。

<FileTree>
- reports/
  - backlog/
    - backlog-plan.md 人が読むための計画書(承認前)
    - backlog-manifest.json プログラムが読むツリー構造とimpl.status
    - backlog-export-result.md 実際に作成したIssue一覧の結果
    - backlog-status.md ダッシュボードのMarkdown書き出し(任意)
    - followup-queue.md 未起票のフォローアップのキュー
    - followup-result.md キューから作成したIssueの結果
    - shared-context/ 実装のたびに読み込む共有知識パック
    - reviews/ レビューラウンドごとの詳細な記録
    - impl-log/ Issueごとの実装ログ
    - epic-review-\<epic\>.md Epicロールアップレビューの結果
</FileTree>

| ファイル/フォルダ | 発行するSkill | 内容 |
|---|---|---|
| `backlog-plan.md` | `export-backlog` | Epic・Sub-Epic・Issueの階層を示す、人が読むための計画書。`AskUserQuestion`で承認を得るまでIssueは作られない |
| `backlog-manifest.json` | `export-backlog`が作成し、`implement-backlog`/`review-issue`/`merge-issue`/`capture-followup`が更新 | Epic/Sub-Epic/Issueごとの`impl.status`と、作成済みIssueへの`remote.url`。[中断と再開](/concepts/resume)の読み取り元 |
| `backlog-export-result.md` | `export-backlog` | 実際に作成されたIssueの一覧と結果 |
| `backlog-status.md` | `report-backlog-status --md`(任意) | ライブダッシュボードのスナップショットをMarkdownで書き出したもの |
| `followup-queue.md` | `capture-followup` | まだIssue化していないフォローアップ項目のキュー。Markdown形式で、人が直接編集できる |
| `followup-result.md` | `capture-followup --flush` | キューから実際に作成されたIssueの結果 |
| `reviews/review-<issue>-round<N>.md` | `review-issue` | そのレビューラウンドで見つかったfinding([B]/[S]/[Q])の詳細な記録 |
| `impl-log/<issue>.md` | `implement-backlog` | Issueごとの実装ログ。進捗コメントや決定事項のミラー |
| `epic-review-<epic>.md` | `implement-backlog --review-epic` | Epic全体を見直すロールアップレビューの結果 |

### `shared-context/` — 実装のたびに読み込む共有知識パック

[Shared-Contextパック](/concepts/shared-context)の実体です。`implement-backlog`が最初に構築し、以降の実装で毎回参照します。

| ファイル | 内容 | 生成元 |
|---|---|---|
| `architecture-guardrails.md` | パッケージ境界・トランザクション境界・技術選定の禁止事項 | `architecture.md`, `tech-stack-fitness.md` |
| `coding-standards.md` | 命名規則・例外処理パターン・テスト方針 | 言語/フレームワーク決定 |
| `ubiquitous-language.md` | ドメイン語彙の日英対応表 | product/architect両方の`ubiquitous-language.md` |
| `data-contracts.md` | テーブル定義・アグリゲート境界・enum変換ルール | `data-model.md` |
| `nfr-budgets.md` | NFR/SLA目標値のクイックリファレンス | `nfr.md`, `sla.md` |
| `decisions.md` | 横断的決定のADR-liteログ(**追記のみ**) | 実装中に蓄積 |
| `review-knowledge.md` | レビューで見つかった教訓の蒸留カタログ(**追記のみ**) | `review-issue`のレビューラウンド |

`decisions.md`と`review-knowledge.md`はappend-onlyログで、他のファイルのように作り直されることはありません。特に`review-knowledge.md`は、**同じ問題を二度実装しないための仕組み**です([review-issueのページ](/skills/backlog/review)に実例があります)。

## 3. `work/` — 進捗・状態管理ファイル

`reports/`が「成果物」を置く場所であるのに対して、`work/`は「今どこまで進んだか」を記録する場所です。productとarchitect、両方のパイプラインが同じファイルを共有します。

| ファイル | 誰が書くか | 内容 |
|---|---|---|
| `pipeline-progress.json` | `/product:start`と`/architect:init-output`、各フェーズ | フェーズごとの状態(`pending`/`in_progress`/`completed`/`failed`/`skipped`)、検証ゲートの判定、出力先。product/architect両方のフェーズが`plugin`フィールドで区別されつつ同じファイルに入る |
| `traceability.json` | 各フェーズ(**追記のみ**) | `VIS-`, `FEAT-`, `ENT-`, `CTX-`, `API-`, `NFR-`, `KN-`などの全トレーサビリティIDのグラフ。`adapt-change`が影響範囲を計算する元データ |
| `context.md` | 各フェーズ(**追記のみ**) | フェーズ間で引き継ぐ決定事項のメモ。product/architect共有の「Open Questions」表を持つ |
| `version-decisions.json` | `implement-backlog`など、依存ライブラリのバージョンを解決するスキル | レジストリで調べた実在バージョンと、選んだ理由・却下したバージョンの記録([implement-backlogのページ](/skills/backlog/implement)参照) |
| `token-usage.json` | トークン使用量を記録するフック(hook) | フェーズ別・モデル別の集計コスト(USD、入力/出力/キャッシュ読み/キャッシュ書きの内訳) |
| `token-usage.jsonl` | 同上 | フック発火ごとに追記される、監査用のログ |
| `token-cost-debug.log` | `report-token-cost --debug`(任意) | ダッシュボード描画時のデバッグ情報 |

[中断と再開](/concepts/resume)・[ライブダッシュボード](/concepts/live-dashboard)・[トークンコストの考え方](/concepts/token-cost)は、いずれもこのフォルダのファイルを読んで動作します。

## 4. `reports/`の外に置かれる出力

生成される「コード」や「デザインシステム」は、企画・設計ドキュメントとは性質が違うため、`reports/`とは別のフォルダに置かれ、別々にバージョン管理されます。

| フォルダ | 発行するSkill | 内容 |
|---|---|---|
| `generated/frontend/` | `generate-frontend`(product, 任意) | React + TypeScript + Vite + Storybookのスキャフォルド。`npm install && npm run dev`でそのまま動く |
| `generated/{service}/` | `generate-scalardb-code`(architect) | Javaソース、リポジトリごとのFake実装(`**/fakes/`)、トランザクションシナリオ統合テスト、`build.gradle`、`Dockerfile`、`scalardb.properties` |
| `generated/infrastructure/{k8s,terraform,helm,ci}/` | `generate-infra-code`(architect) | Kubernetesマニフェスト、Terraformモジュール、Helm値、CI用ワークフロー |
| `design-system/{name}/` | `design-system`(product, 任意・独立実行) | `tokens.json`(DTCG)、`tokens.css`、`components.md`、`guidelines.md`、`manifest.json`、`preview.html` |

<Panel title="なぜ別管理なのか">
`reports/`は「決定の記録」であり、後から読み返すための資料です。一方`generated/`と`design-system/`は「実際に動く/使う」ためのものです。`design-system/`は複数のプロダクトで再利用したり、バージョンを上げ下げしたりする対象なので、企画フェーズの一部としてではなく独立して管理されます。
</Panel>

## 5. architectパイプラインを単独で使う場合の出力

productパイプラインを経由せず、`architect`を直接の起点として使う場合は、これまでとは別の番号付きフォルダが作られます。[Architectパイプライン](/skills/architect-pipeline)で説明した2つの経路(グリーンフィールド/レガシー)に対応しています。

:::warning[番号の意味は入り口ごとに独立しています]
例えば`reports/03_domain/`(product起点)と`reports/03_design/`(architect単独起点)は、どちらも「3番目のフォルダ」ですが別物です。通常、1つのプロジェクトではどちらか一方の入り口しか使わないため、実際に両方が同時に存在することは想定されていません。
:::

**グリーンフィールド経路**

真新しいプロダクトを一から作るときの経路です。

| ファイル | 発行するSkill | 内容 |
|---|---|---|
| `reports/00_requirements/requirements-definition.md` | `define-requirements` | 要件定義 |
| `reports/00_requirements/data-transaction-requirements.md` | `define-requirements` | データ・トランザクションの要件 |
| `reports/00_requirements/open-questions.md` | `define-requirements` | `work/context.md`のOpen Questionsを描画したビュー |
| `reports/00_requirements/scalardb-applicability.md` | `define-requirements`(ScalarDB使用時のみ) | ScalarDBの適用可否 |
| `reports/03_design/domain-analysis.md` | `map-domains` | ドメイン分析 |
| `reports/03_design/api-style-decisions.md` / `.json` | `design-api` | REST/GraphQL/gRPCなどのAPIスタイル決定 |
| `reports/03_design/api-specifications/` | `design-api`(+`design-graphql`) | OpenAPI/GraphQL/gRPC/AsyncAPIの仕様書 |
| `reports/06_implementation/*.md`, `api-contract-map.json` | `design-implementation` | API層・ドメインサービス・リポジトリ・値オブジェクトの実装仕様 |
| `generated/{service}/`, `generated/infrastructure/` | `generate-scalardb-code`, `generate-infra-code` | 実装コードとインフラコード([reports/の外に置かれる出力](#4-reportsの外に置かれる出力)を参照) |

**レガシー経路**

既存システムを調べ直し、改修や再設計を行うときの経路です。

| ファイル | 発行するSkill | 内容 |
|---|---|---|
| `reports/before/{project}/technology-stack.md` 他3〜4ファイル | `investigate` | 技術スタック、コードベース構造、負債、DDD readiness(必要に応じてセキュリティ評価) |
| `reports/01_analysis/system-overview.md` 他3ファイル | `analyze` | システム概要、既存の用語対応表、アクター/権限、ドメインとコードの対応 |
| `reports/01_analysis/data-model-analysis.md`, `er-diagram-current.md` | `analyze-data-model`(任意) | 既存データモデルの分析、現状のER図 |
| `reports/02_evaluation/mmi-*.md` | `evaluate-mmi`(並列) | モジュール成熟度指標(MMI)の評価 |
| `reports/02_evaluation/ddd-*.md` | `evaluate-ddd`(並列) | DDD戦略/戦術面の評価 |
| `reports/02_evaluation/integrated-evaluation.md`, `unified-improvement-plan.md` | `integrate-evaluations` | 2つの評価を統合した改善計画 |
| `reports/03_design/bounded-contexts-redesign.md`, `context-map.md` | `redesign` | 境界コンテキストの再設計 |
| `reports/03_design/target-architecture.md`, `transformation-plan.md` | `design-microservices` | 目標アーキテクチャと移行計画 |
| `reports/04_stories/domain-story-{domain}.md` | `create-domain-story`(任意) | Domain Storytelling |
| `reports/03_design/scalardb-*.md` または `data-layer-design.md` | `design-scalardb` / `design-data-layer`(条件分岐) | データ層の設計 |
| `reports/review/individual/review-*.json`(最大7種) | `review-consistency`等(並列) | [レビュー系](/skills/architect-pipeline)の各視点の結果 |
| `reports/review/review-synthesis.md` / `.json` | `review-synthesizer` | 全視点を統合したGo/No-Go判定 |
| `reports/00_summary/full-report.html` | `report` | 統合HTMLレポート |
| `reports/review/report-quality-review.md` | `review-report` | レポート自体の品質レビュー |

どちらの経路でも共通して、必要に応じて次のフォルダが手動実行のスキルによって作られます。

| フォルダ | 発行するSkill | 内容 |
|---|---|---|
| `reports/03_design/aggregates/aggregate-manifest.json` | `design-aggregate`(任意) | 集約設計(ルート・不変条件・コマンド・リポジトリ) |
| `reports/03_design/state-machines/state-machine-manifest.json` | `design-state-machine`(任意) | 状態遷移設計(状態×イベントの全マスの判定) |
| `reports/03_design/domain-event-catalog.json` / `.md` | `design-aggregate`(発行)、`design-microservices`(消費側を完成) | イベントの発行者・購読コンテキスト・配信契約(コンテキストマップのPublished Language) |
| `reports/03_design/adr/adr-NNN-<slug>.md`, `index.md` | `redesign`(ログを開始)、`design-microservices`/`design-scalardb`/`design-data-layer`/`design-api`(追記) | Architecture Decision Records(横断的な決定ログ、追記のみ) |
| `reports/05_estimate/` | `estimate-cost`, `estimate-token-cost` | クラウド/ScalarDBライセンス/運用コストの見積もり、トークンコストの見積もり(`token-cost-estimate.md`) |
| `reports/07_test-specs/` | `generate-test-specs`, `generate-characterization-tests`(レガシー経路), `generate-acceptance-tests` | 単体/統合/契約/性能テストの仕様、BDDシナリオ、特性テストカバレッジ(`characterization-test-coverage.md`)、受入テストカバレッジ(`acceptance-test-coverage.md`) |
| `reports/08_infrastructure/` | `design-security`, `design-observability`, `design-disaster-recovery` | セキュリティ設計、監視設計、災害対策設計、デプロイ手順 |
| `reports/09_verification/` | `verify-implementation --gate` | ビルド・テスト・SAST・依存スキャン・カバレッジ/ミューテーションスコアなどを通す[品質ゲート(8段階)](/skills/backlog/implement)の結果 |

<Panel title="なぜこの構造が重要か">
`reports/`は単一の真実源(single source of truth、情報が食い違わないよう、必ずここを見ればいいと決めた1つの場所)です。後続のスキルはすべて、このディレクトリを読んで動作します。だからこそ、番号付きディレクトリの意味(フェーズの順序)を崩さないことが大切です。順序を崩すと、パイプライン全体の一貫性が保てなくなります。詳しくは[基本の仕組み](/concepts)を参照してください。
</Panel>