出力ディレクトリ構造
NexusArchitectが使うreports/とwork/のディレクトリ構造、フォルダ・ファイルそれぞれの役割について詳しく説明します
NexusArchitectは、次のディレクトリ構造を使います(存在しない場合は、init-output系のSkillが作成します)。
- reports/ 企画・設計・レビューの成果物
- work/ 進捗・トレーサビリティ・コストの記録
- generated/ 実際に動くコード
- design-system/ デザインシステム
reports/が唯一の真実源(single source of truth)であるのに対して、work/はパイプラインの状態を記録するファイル群です。generated/(フロントエンド/バックエンド/インフラのコード)とdesign-system/(トークン・コンポーネント一覧)は、reports/とは別に管理されます。
1. productパイプラインの出力(reports/00_core/ 〜 reports/report/)
/product:startで作られる、番号付きフォルダです。フォルダの番号はフェーズの順序をそのまま表しています。
- 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レポート、レビュー結果
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は、検証ゲートそのものです。判定結果自体は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スキル(バックログ運用)が書き込むフォルダです。reports/の番号付きフォルダ(product側)がどんな入り口で作られたものでも、ここには関係なく取り込めます。
- 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ロールアップレビューの結果
- backlog/
| ファイル/フォルダ | 発行する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。中断と再開の読み取り元 |
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パックの実体です。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のページに実例があります)。
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のページ参照) |
token-usage.json |
トークン使用量を記録するフック(hook) | フェーズ別・モデル別の集計コスト(USD、入力/出力/キャッシュ読み/キャッシュ書きの内訳) |
token-usage.jsonl |
同上 | フック発火ごとに追記される、監査用のログ |
token-cost-debug.log |
report-token-cost --debug(任意) |
ダッシュボード描画時のデバッグ情報 |
中断と再開・ライブダッシュボード・トークンコストの考え方は、いずれもこのフォルダのファイルを読んで動作します。
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 |
5. architectパイプラインを単独で使う場合の出力
productパイプラインを経由せず、architectを直接の起点として使う場合は、これまでとは別の番号付きフォルダが作られます。Architectパイプラインで説明した2つの経路(グリーンフィールド/レガシー)に対応しています。
真新しいプロダクトを一から作るときの経路です。
| ファイル | 発行する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/の外に置かれる出力を参照) |
既存システムを調べ直し、改修や再設計を行うときの経路です。
| ファイル | 発行する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等(並列) |
レビュー系の各視点の結果 |
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段階)の結果 |