docs: ドキュメント配置ルール(SSOT)確立

## 追加内容
- CLAUDE.md にドキュメント配置ルール(SSOT)セクション追加
- DOCS_LAYOUT.md (SSOT): 置き場所ルール定義
- phases/README.md: Phase ドキュメント説明
- design/README.md: 設計図ドキュメント説明
- investigations/README.md: 調査ログ説明

## ルール概要
1. **Phase 文書** → phases/phase-<N>/
2. **設計図** → design/
3. **調査ログ** → investigations/ (結論を 10-Now/20-Decisions に反映)

## 導線
- CLAUDE.md で概要説明
- DOCS_LAYOUT.md で詳細定義(SSOT)
- 各フォルダ README で参照方法

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
nyash-codex
2025-12-14 18:27:24 +09:00
parent e4678585d5
commit 4b87b6cc88
12 changed files with 289 additions and 22 deletions

View File

@ -0,0 +1,81 @@
# Docs Layout (SSOT)
Status: SSOT
Scope: `docs/development/current/` 以下の「置き場所ルール」と、SSOT/履歴メモの混在を防ぐための最小ガイド。
## 目的
- 入口(読む順序)と、詳細(設計図/調査/Phaseログを分離して迷子を防ぐ。
- “Phase 文書が増えても” SSOT が埋もれないようにする。
- 大規模移動はしない(リンク切れ回避)。以後の追加分から秩序を作る。
## ディレクトリの役割(推奨)
### `docs/development/current/main/`(入口・現状)
ここは「まず読む」入口を置く場所。SSOT を全部ここに置かない。
- 入口(例): `00-Overview.md`, `01-JoinIR-Selfhost-INDEX.md`, `10-Now.md`, `20-Decisions.md`, `30-Backlog.md`
### `docs/development/current/main/design/`設計図・SSOT寄り
設計の SSOT / 長期参照の設計図を置く。
- 原則: Phase 依存のログ/作業記録は置かない(それは phases へ)。
- 例: JoinIR の設計、Boundary/ExitLine の契約、Loop パターン空間、runtime/box 解決の地図。
### `docs/development/current/main/investigations/`(調査ログ)
不具合調査のログ、切り分け、暫定メモを置く。
- 原則: “結論” は `10-Now.md` / `20-Decisions.md` / 該当 design doc に反映し、調査ログ自体は参照用に残す。
- 原則: 調査ログを SSOT にしない(参照元を明記して“歴史化”できる形にする)。
### `docs/development/current/main/phases/`Phaseログ
Phase ごとの記録・完了サマリ・実装チェックリストを置く。
- 推奨構造:
- `docs/development/current/main/phases/phase-131/`
- `docs/development/current/main/phases/phase-131/131-03-llvm-lowering-inventory.md`
- `docs/development/current/main/phases/phase-131/131-11-case-c-summary.md`
## ドキュメントの種別(ファイル先頭に明記)
追加/更新する文書の先頭に、最低限これを付ける。
```
Status: SSOT | Active | Historical
Scope: ...
Related:
- <入口/SSOT>
```
- `SSOT`: 現行の正本(同じテーマの“別名ファイル”を増やさない)。
- `Active`: 現行だが SSOT ではない(実装の手順書/チェックリスト等)。
- `Historical`: 参照用(当時の調査・ログ)。入口や Now から “歴史” としてリンクする。
## 移行ポリシー(リンク切れ防止)
既存のファイルは大量移動しない。移動が必要な場合は必ず旧パスに“転送スタブ”を残す。
例(旧ファイルの内容を最小化):
```
# Moved
Moved to: docs/development/current/main/phases/phase-131/131-03-llvm-lowering-inventory.md
```
## 命名(推奨)
- Phase 文書: `phase-<N>/` + `<N>-<NN>-<topic>.md`(同一フェーズ内で並べ替えが自然)
- 調査ログ: `<topic>-investigation-YYYY-MM-DD.md` など(時系列が分かる形)
- 入口/SSOT: “Phase番号を入れない” ことを基本にする(寿命が長いので)
## 運用の最小ルール
- 新しい Phase 文書は `main/phases/` に入れる(`main/` 直下に増やさない)。
- 設計図SSOT`main/design/` に寄せるPhase の完了サマリと混ぜない)。
- `10-Now.md` は「現状の要約+正本リンク」に徹し、詳細ログの本文は抱え込まない。