---
lifecycle: draft
created: 2026-07-25
updated: 2026-09-06
---

# project-structure-v0（生成物の置き場所）契約

- 日付: 2026-07-25
- 状態: **ドラフト・要オーナーレビュー**
- 前提: `contract-2026-07-17-data-contract-versioning.md`（版管理三原則の正本。本契約は
  データスキーマの版管理ではなくプロジェクト内の置き場所規約のため三原則を直接は適用しないが、
  契約文書としての様式は踏襲する）、`contract-2026-07-25-recipe-v0.md`（直前の姉妹契約。
  文体・様式・ドラフト明記の先例）、`docs/contract-2026-07-13-m1-m4.md`（`edit.json` 等、
  現在プロジェクトルート直下に置かれている既存契約ファイルの正本）
- 発端: 実機フィードバック 2026-07-25 — 実プロジェクトのルートに `frame-*.png` 9 枚
  （キーフレーム視認証跡）・ad-hoc 検証スクリプトとその結果 JSON・`final.mp4` が散乱。
  「もう全部構造化できないと困る」。生成物の宛先を層として確定し契約化する。
  判断根拠・出典調査は非公開の内部記録で管理する（本リポには置かない方針）
- スコープ: プロジェクトディレクトリ内の生成物の置き場所規約（層の定義・ルート直下原則・
  削除安全とレガシーの定義）と、既存スキル・テンプレへの出力先明記のみ。**既存プロジェクトの
  移行・強制移動スクリプト・GUI 変更・`edit-lint`/`render-cut` のコード（`packages/**`）変更・
  スキーマ変更・ルート直下の `cache/`（レガシー）の扱い裁定は非スコープ**（§7）

## 0. 位置づけ — 生成物の宛先を 1 枚で言い切る

本契約が定めるのは「どのファイルがどこに書かれるか」だけである。新しいデータスキーマも、
新しい実行手順も導入しない。既存のスキル・CLI（`edit-lint`・`render-cut`・`analyze-footage`
等）が実際に生成しているファイル種別を棚卸しし、正準の置き場所を 1 枚の表（§1）に確定させ、
スキル文書とプロジェクト雛形にその宛先を明記することで、生成物がプロジェクトルートへ
散らかる事故を構造的に防ぐ。

統制の柱は「隠し領域隔離」（削除安全な層をドット領域へ分離する）と「スキルが場所を教える」
（スキル文書へ出力先を明記する）の 2 本である。「paths 宣言」（プロジェクトごとの
置き場所設定 UI）は本契約のスコープ外（§7）。

## 1. 層の定義（正準の置き場所）

| 層 | 場所 | 書き手 |
|---|---|---|
| 人間の一次素材 | `assets/`（下位分類自由） | 人間・取り込み UI |
| 企画・プラン | `planning/` | スキル + 人間承認 |
| 仮枠のシーン JSON（AI が書く・人が微調整。仮枠の meta の `frame.content.scene` が指す） | `planning/frames/` | スキル・仮枠の編集 |
| エージェント中間物・ad-hoc 検証スクリプトと結果 | `.akari/work/` | スキル・エージェント |
| 検証証跡・レポート（キーフレーム視認 PNG・render-report 等） | `.akari/reports/` | スキル |
| 絵コンテ（タイムラインの印刷・初回だけ・AI は後から読まない） | `.akari/reports/storyboard/` | スキル |
| キャッシュ（サムネ・プロキシ等の再生成可能物） | `.akari/cache/` | アプリ・スキル |
| 納品物 | `exports/` | `render-cut` |
| 契約サイドカー（既存） | `.akari/`（`sidecars/` `diffs/` `events/` 等） | 既存のまま |

`planning/frames/<stem>.scene.json` は仮枠（生成 v0 契約）の中身を記述する正本で、変更履歴に入る（`planning/**`）。仮枠の絵（png）と meta は従来どおり `assets/generated/`。

`.akari/` 直下にはこの表にない契約サイドカーファイルも存在する（`intake.json`・
`workflow.json`・`connections.json`・`lint.json`・`render.json` 等）。これらは各自の
契約文書が正本であり、本契約は「置き場所の層」を追加で確定させるだけで、個々のファイル形は
変更しない。

## 2. 原則

### 2-1. ルート直下原則

**プロジェクトルート直下への新規ファイル作成は、`edit.json` / `captions.json` /
`review.json` 等の既存契約ファイルのみ**とする。それ以外の新規ファイルをプロジェクトルート
直下に書くことは契約違反である。

- 上記 3 ファイルは各自の契約文書（[contract-2026-07-13-m1-m4.md](contract-2026-07-13-m1-m4.md)、
  [contract-2026-07-20-review-json-v1-annotation-model.md](contract-2026-07-20-review-json-v1-annotation-model.md)
  等）でルート直下配置が既に確定しているため、本契約はその配置を変更しない
- `frame-*.png`・ad-hoc 検証スクリプトとその結果・最終書き出し前の中間ファイル等、上記
  3 ファイル以外の生成物は、性質に応じて §1 の層へ振り分ける（具体例は §4）
- 新しいトップレベル契約ファイルを追加する場合（将来の話）は、本契約の改訂を通す

#### 2026-08-26 追記: ルート直下の判断記録・分析レポート

- `decision-log.md` は analyze-project と edit-plan が共同追記する判断履歴の単一 SSOT であり、
  プロジェクトルート直下の正当な契約ファイルとする（根拠:
  `skills/edit-plan/report-guide.md` の `decision_log` 節）
- `analysis-report.html` は analyze-project が生成し edit-plan が読む正式な分析レポートであり、
  プロジェクトルート直下の正当な契約ファイルとする（根拠:
  `skills/edit-plan/workflow.md` §1）
- この追記は上記 2 ファイルを §2-1 の許可リストへ追加するものであり、その他のファイルに
  ルート直下配置を許可しない

### 2-2. 削除安全の定義

`.akari/work/` と `.akari/cache/` は**再生成可能・削除安全**と定義する。

- `.akari/work/`: エージェントが実行の過程で作る中間物・ad-hoc 検証スクリプトとその実行結果。
  同じ入力から同じ手順を再実行すれば再現できる想定のものだけを置く
- `.akari/cache/`: サムネイル・プロキシ等、原本（`assets/`）または承認済み成果物
  （`edit.json` 等）から機械的に再生成できるものだけを置く
- この 2 ディレクトリは**バックアップ対象外としてよい**（削除しても、原本または
  正本ファイルさえ残っていれば再現できるため）。`.akari/reports/` は検証証跡であり
  削除安全とは定義しない（キーフレーム視認や render-report は「その時点で人間が確認した
  記録」であり、再実行しても同じ内容が再現される保証がない）

## 3. レガシー定義

既存の実プロジェクト（本契約より前に作られたプロジェクト）のルート直下にある `cache/`
ディレクトリ、および `frame-*.png` 等の散乱ファイルは**レガシーと定義する**。

- 移行（レガシー資産を §1 の層へ移す作業）は本契約のスコープ外
- 強制的にファイルを移動・削除するスクリプトは作らない
- 既存プロジェクトの `cache/`（ルート直下）を今後どう扱うか（`.akari/cache/` への統合、
  削除、放置のいずれか）は**オーナー裁定事項**とし、本契約は裁定を代行しない（§6）
- 新規プロジェクト（本契約適用後にテンプレから作られるプロジェクト）は §1 の層に
  最初から従う。レガシー定義は「過去に作られたプロジェクトを免責する」ためのものであり、
  今後の新規生成物には適用されない

## 4. 具体例 — 発端の実例 3 種の行き先

発端の実機フィードバックで観測された散乱ファイル 3 種は、本契約下では
それぞれ次の層へ行く。

| 実例 | 性質 | 本契約下の行き先 |
|---|---|---|
| `frame-*.png`（キーフレーム視認証跡） | 検証証跡・レポート | `.akari/reports/`（`edit-lint`・`render-cut` の視認スクリーンショットと同じ層。§1） |
| `negative-rule-check.mjs` + `negative-rule-check-result.json`（エージェントの ad-hoc 検証スクリプトと結果） | エージェント中間物 | `.akari/work/`（スクリプト本体と実行結果 JSON を同じディレクトリへ。§1・§2-2） |
| `final.mp4` | 納品物 | `exports/`（`render-cut` の出力契約どおり。§1） |

いずれも新しいファイル形・命名規則を導入するものではない。既に §1 で確定した層のうち、
どの層に対応するかを具体例で明示しただけである。

## 5. 適用箇所

本契約は次のスキル文書・プロジェクト雛形に出力先として反映する（各ファイルの追記箇所が
本契約の実施箇所である）。

- `skills/edit-lint/SKILL.md` — キーフレーム視認の画像・QA 生成物は `.akari/reports/`、
  一時スクリプトは `.akari/work/`
- `skills/render-cut/SKILL.md` — 最終 MP4 は `exports/`、視認スクショは `.akari/reports/`、
  中間ファイルは `.akari/work/`
- `skills/edit-plan/workflow.md` — ad-hoc 検証スクリプト・実験生成物は `.akari/work/`
- `skills/analyze-footage/SKILL.md` — 既存の `.akari/sidecars/` 規約が本契約の一部である旨の
  相互リンク
- `templates/project-default/`（`.akari/work/` `.akari/reports/` `.akari/cache/` を実
  ディレクトリとして追加）と、その `CLAUDE.md` / `AGENTS.md` の要約 3 行 + 本契約への参照

## 6. オーナー裁定事項

- 既存実プロジェクトのルート直下 `cache/` と散乱ファイルをレガシーと定義し、移行を
  本契約のスコープ外とすること（§3）。今後これらをどう扱うか（統合・削除・放置）は
  オーナー裁定が必要
- 「paths 宣言」（プロジェクトごとに置き場所を UI で変更できる機構）を本契約で導入しない
  という判断（§0・§7）。導入する場合は別契約が必要

## 7. 次段（本契約のスコープ外）

- 既存プロジェクトのレガシー資産の移行・強制移動スクリプト（§3）
- 素材タブ等 GUI の未整理セクション対応（別レーンの領分）
- `edit-lint` / `render-cut` のコード（`packages/**`）変更 — 本契約は出力先の文書上の明記
  のみで、CLI の書き込み先ロジックを変更しない
- スキーマ変更（`edit.json` 等の既存契約ファイル形は不変）
- 「paths 宣言」（プロジェクトごとの置き場所カスタマイズ UI）の導入
- ルート直下 `cache/`（レガシー）の最終的な扱いの裁定（§3・§6）

## 8. 追記（2026-08-30）— `motion/` を正本ディレクトリとして登録

`contract-2026-08-30-edit-json-v2-object-tree-v0.md` / `contract-2026-08-30-motion-and-keyframes-v0.md` により、
プロジェクト直下に **`motion/`** を追加する。

| 用途 | 置き場 | 作成者 | 性質 |
|---|---|---|---|
| キーフレーム曲線の袋（`motion/<group-id>.json`。edit.json の `keyframes: { path, count }` から参照）| `motion/` | edit-store（保存時に inline から振り分け）| **正本**（再生成不可。`.akari/cache/` ではない）|

- edit.json / captions.json と同じトランザクションで保存され、同じ lint ゲートを通る
- §2 の「ルート直下への新規ファイル作成は正本ファイルに限る」の例外ではなく、正本ファイルの追加である

## 9. 追記（2026-09-02）— `akari clean` と `.akari/work/` の下位規約

§2-2 の「`.akari/work/` は再生成可能・削除安全」という定義は維持する。ただし、既存の実プロジェクトで
人が編集した計画・生成器と使い捨て出力が同居し、一括削除によって再生成できないデータを失った実績が
ある。この移行期の安全策として、`akari clean` は `.akari/work/` 全体を削除可能とは判定せず、次の
下位規約と目印で分類できる範囲だけを扱う。

| 場所・目印 | 性質 | `akari clean` の扱い |
|---|---|---|
| `.akari/work/tmp/` | 同じ入力と手順から作り直せる使い捨て | 削除可能 |
| `.akari/work/keep/` | 計画・生成器・手編集ファイルなど作り直せないもの | 保持 |
| ディレクトリ直下の `.akari-disposable` | そのディレクトリ配下を使い捨てと宣言する空ファイル | 削除可能 |
| ディレクトリ直下の `.akari-keep` | そのディレクトリ配下を保持すると宣言する空ファイル | 保持 |
| 上記のいずれにも当たらない `.akari/work/` 配下 | 正本混在の可能性を否定できない | 判断保留 |

目印は置いたディレクトリの配下全体に効き、上位または同じディレクトリに `.akari-keep` があれば
`.akari-disposable` より保持を優先する。スキルは、再生成に手間のかかる計画・生成器・手編集ファイルを
`.akari/work/` 直下へ新しく置かず、`keep/` へ置く。既存の
`.akari/work/semantic-keep-plan.json` や `.akari/work/gen-timeline.mjs` 等は互換性のため移動せず、
この規約の適用後に新しく作るものから `tmp/` / `keep/` を使い分ける。

`akari clean` は、削除可能・保持・判断保留を宣言表に基づいて一覧し、既定では削除しない。明示承認後も
削除するのは削除可能と分類されたものだけであり、直近 60 分以内に更新された候補とシンボリックリンクは
判断保留に移す。この限定されたオプトイン削除は、§3 のレガシー資産を強制移動・削除しない原則と両立する。

`assets/generated/` の生成素材には、可能な限り `<file>.meta.json` を添える。由来サイドカーの形は次とし、
`provenance` は `asset-meta.schema.json` と同じキー名を使う。`akari clean` はこれを読み取って由来を表示し、
`origin` の参照先が無い場合は警告する。サイドカーを書く生成器の実装はこの追記の範囲外である。

```json
{
  "version": 1,
  "provenance": {
    "origin": "planning/plan.json",
    "generator": "tool-name",
    "inputs": ["assets/source.mp4"],
    "created_at": "2026-09-02T00:00:00.000Z"
  }
}
```

## 10. 追記（2026-09-03）— 変更履歴に何を入れるか（`.gitignore` 雛形）

§2-2 と §9 が扱うのは「ディスク上で消してよいか」である。本節が定めるのは**別の軸**、
「変更履歴（節目ごとの自動スナップショット）に入れるか」である。納品した `exports/*.mp4` は
ディスクでは保持だが履歴には入れない、というように 2 つの軸は独立に決まる。

雛形の `.gitignore` が生成物を除外していなかったため、40 秒の動画 1 本のプロジェクトで
`.git` が 4.2 GB に達した（6 プロジェクト合計で `.git` が全体の 70%・素材は 4%）。
原因は「同じ拡張子の知識が 2 か所に分かれ、片方だけが育っていた」ことである。

| 変更履歴に入れる | 入れない |
|---|---|
| `edit.json` / `captions.json` / `review.json` / `plan.json` | `assets/**`（原本） |
| `planning/**` / `.akari/events/**` / `motion/**` | 生成された映像・音声・画像（下表の拡張子） |
| `.akari/reports/**` の JSON・HTML（証跡の実体） | `.akari/render-tmp/**` / `.akari/cache/**` / `.akari/diffs/**` |
| `.akari/sidecars/**`（映像を含めて全部） | |

- 除外する拡張子: `.mp4` `.mov` `.m4v` `.webm` `.mkv` `.avi` `.png` `.jpg` `.jpeg` `.gif`
  `.webp` `.bmp` `.wav` `.mp3`
- 例外は 2 つだけである。`.akari/sidecars/**` は分析に手間がかかるため映像でも履歴に残す。
  `.akari/reports/**` は拡張子で分かれ、png は外れ JSON・HTML は残る
- 単一の出所は `packages/akari-launcher/src/history-policy.mjs`。`.gitignore` 雛形
  （`templates/project-default/.gitignore` と `project-scaffold` の `PROJECT_GITIGNORE`）と、
  「変更を見る」の除外判定（`isInternalOrBinaryPath()`）は**どちらもここから導出する**。
  片方だけに拡張子を足すことは契約違反である

### 移行

アプリはプロジェクトを開いたとき、`.gitignore` を現行の内容へ揃え、新たに対象となった
追跡済みファイルを `git rm --cached` で履歴から外し、1 本コミットする。

- **ディスク上のファイルは消さない**（利用者の成果物であり、消してよいかは §9 の宣言表が別に判断する）
- 履歴そのもの（過去のコミットが抱える blob）は書き換えない。これは利用者の明示操作の領域であり、
  移行だけでは `.git` は縮まず横ばいになる
- `.gitignore` のうちアプリが管理するのは `# >>> AKARI Video ... >>>` から `# <<< ... <<<` までの
  囲みだけとする。囲みの外に利用者が書き足した行は消さない
- 自分がルートである git リポジトリのときだけ動く。親リポジトリの中に置かれたプロジェクトは、
  こちらが管理していないリポジトリの追跡対象を黙って変えないため対象外とする（§3 の
  「強制的にファイルを移動・削除するスクリプトは作らない」と同じ抑制）

### 2026-09-06 追記: 絵コンテの置き場（判子は一回 契約 §5.2 / §14-4）

絵コンテは `edit.json` / `captions.json` から描くタイムラインの派生ビューで、
置き場は `.akari/reports/storyboard/`（レポート層 = 削除安全）とする。
初回だけ描き更新しない・入力側に置かない・AI は後から読まない。直すときはタイムラインを
直して描き直す。