448bf3d8c5
Documentation: - Move completion reports to docs/archive/reports/ - Add phase232-238 design/inventory documents - Update joinir-architecture-overview.md - Add doc-status-policy.md Code refinements: - ExprLowerer: condition catalog improvements - ScopeManager: boundary clarifications - CarrierInfo: cleanup 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
69 lines
3.6 KiB
Markdown
69 lines
3.6 KiB
Markdown
# Development Docs Status & Scope Policy
|
||
|
||
このファイルは、開発ドキュメント（特に `docs/development/` 配下）が増えたときに
|
||
「どれが現役の設計か」「どれが歴史メモか」「どれを入口に読むべきか」を迷わないようにするための運用ルールだよ。
|
||
|
||
## 1. ステータス分類
|
||
|
||
開発ドキュメントの先頭付近に、次のいずれか（または組み合わせ）のステータスを明示することを推奨するよ。
|
||
|
||
- `Status: SSOT`
|
||
- 単一情報源（Single Source of Truth）。同じ内容を別ファイルに複製しない前提の設計ドキュメント。
|
||
- 変更があったらまずここを更新し、Phase 文書などは補足とする。
|
||
- `Status: Active`
|
||
- いまの開発ラインで直接参照される現役ドキュメント。
|
||
- 設計・実装の前提として読むことを想定。
|
||
- `Status: Historical`
|
||
- 過去フェーズのメモや調査ログ。読み物としては有用だが、設計の SSOT ではない。
|
||
- 先頭付近に「現行仕様は <path> を参照」と追記できるとさらに親切。
|
||
- `Status: VerificationReport`
|
||
- スモーク/ゴールデン/自動テストの実行レポート。
|
||
- 仕様そのものではなく、「いつ・何を確認したか」の記録。
|
||
|
||
完全移行は必須ではないけれど、新しく書くドキュメントや編集するタイミングで
|
||
少しずつステータスを追記していく運用を想定しているよ。
|
||
|
||
## 2. スコープと入口の書き方
|
||
|
||
ステータスに加えて、「このドキュメントは何の入口なのか」を 1–3 行で明示しておくと迷いにくくなるよ。
|
||
|
||
推奨フォーマットの例：
|
||
|
||
```markdown
|
||
Status: SSOT, Active
|
||
Scope: JoinIR ライン全体（Loop/If/Boundary）の箱と契約の設計を横串で定義する。
|
||
See also: docs/development/current/main/01-JoinIR-Selfhost-INDEX.md
|
||
```
|
||
|
||
- `Scope:` では「このファイルを読んだら何が分かるか」を 1 文で書く。
|
||
- `See also:` では関連する INDEX や補助ドキュメントにリンクする（必要な場合だけで OK）。
|
||
|
||
## 3. JoinIR / Selfhost まわりの現時点の整理
|
||
|
||
特に問い合わせが多い JoinIR / Selfhost については、次を入口として扱うよ。
|
||
|
||
- トピック別 INDEX
|
||
- `docs/development/current/main/01-JoinIR-Selfhost-INDEX.md`
|
||
- JoinIR SSOT
|
||
- `docs/development/current/main/joinir-architecture-overview.md`（Status: SSOT, Active 想定）
|
||
- Selfhost Stage‑B/Stage‑1/Stage‑3 フロー
|
||
- `docs/development/current/main/selfhost_stage3_expected_flow.md`（Status: Active 想定）
|
||
|
||
これらの詳細な読み順や関連ドキュメントは、INDEX 側に集約していく方針だよ。
|
||
|
||
## 4. 重複ドキュメントの扱い方
|
||
|
||
「同じようなことが複数のファイルに書かれている」場合は、次の順番で整理するのがおすすめだよ。
|
||
|
||
1. **SSOT を決める**
|
||
- 設計として参照されるべき 1 ファイルを選び、`Status: SSOT` を付ける。
|
||
2. **他ファイルは役割を限定する**
|
||
- 例: `Status: Historical` または `Status: VerificationReport` を付ける。
|
||
- 冒頭に「現行仕様は <SSOT パス> を参照」と追記する。
|
||
3. **新しい情報は SSOT に寄せる**
|
||
- フェーズメモから仕様が昇格したら、SSOT 側を先に更新し、メモ側にはリンクだけを残す。
|
||
|
||
いきなり全ファイルを一括変換するのではなく、
|
||
「触るタイミングでステータスとスコープを少しずつ整える」方針で進めると安全だよ。
|
||
|