05 記録・ドキュメント — 決定ログ・日記・MOC
「なぜそうしたか」を永続させるためのドキュメント設計
2層ドキュメント構造
01_DECISIONS/<project>/ ← 技術的詳細（過去形）
「なぜそう決めたか」の変遷記録
10_DAILY/YYYY-MM-DD.md ← 日次サマリー（ハブ）
「今日何をしたか」のサマリー + 01_DECISIONSへのリンク
重要な原則: 日記には詳細を書かない。詳細は 01_DECISIONS/ に書き、日記はリンクのみ。
決定ファイルの書き方
テンプレート
# YYYY-MM-DD: <タイトル>
## 決定事項
[何を決めたか、一行で]
## 背景
[なぜこの問題に直面したか]
## 選択した解決策
[実際に選んだアプローチ]
## 却下した代替案
- **代替案A**: [内容] → 却下理由: [理由]
- **代替案B**: [内容] → 却下理由: [理由]
## 実装詳細
[実際のコード・コマンド・設定値]
## 未解決問題
- [次のステップ or 判断待ちの事項]
実例
# 2026-05-15: PostgreSQLからSQLiteへの移行
## 決定事項
開発環境のDBをPostgreSQLからSQLiteに変更する
## 背景
開発環境のセットアップが複雑でオンボーディングコストが高い。
ローカル開発にPostgreSQLは過剰。
## 選択した解決策
- 開発: SQLite（ファイルDB）
- 本番: PostgreSQL（変更なし）
- ORM: SQLAlchemyで抽象化済みのため変更が最小
## 却下した代替案
- **Docker Composeで統一**: 設定複雑性は解消できるが重い → 却下
- **SQLiteを本番でも使用**: スケーラビリティリスクあり → 却下
## 実装詳細
DATABASE_URL=sqlite:///./dev.db # .env.development
DATABASE_URL=postgresql://... # .env.production
## 未解決問題
- ステージング環境のDB設定（次のスプリントで対応）
構想段階の合意の永続化（📝WIPメモ）
決定ログ（01_DECISIONS/）は「確定した決定」を記録しますが、「合意はしたが spec（設計書）は未作成」の中間状態が存在します。この中間状態の設計判断（構想）は会話の中にしか存在せず、次セッションで消えてしまう問題があります。これを防ぐため、構想段階の合意は バックログ.md 該当タスク直下の 📝WIPメモ として永続化します（真実のソースを増やさない・タスクと運命共同体でゴミ化防止）。
ABC の3層（振り分け）
合意段階の内容は、重さで3層に振り分けます:
| 層 | 名前 | 場所 | 条件 |
|---|---|---|---|
| A | 構想（📝WIPメモ） | バックログ.md 該当タスク直下 |
設計判断を含む（複数案評価・トレードオフ記録） |
| B | バックログ行 | バックログ.md の通常タスク行 |
単一アクションで完結 |
| C | spec | docs/superpowers/specs/ |
実装可能な詳細仕様まで詰まっている |
判定不能 → 構想（安全側）
構想メモの形式（軽量）
該当タスク行の直下にインデントブロックで記載します:
- [ ] <タスク名> — <概要>
- 📝 構想(YYYY-MM-DD): <方針1-2行>
- 経緯: <候補/選択理由/却下>
- 次タスク: <承認済・設計未着手の内容>
なぜバックログ直下か（設計根拠）
行方不明防止に必要なのは「場所」でなく「タスクとの紐付け（関係）」。バックログ直下は関係を構造的に持つ唯一の方式で、タスクの運命共同体となります（タスク破棄時にメモも消える＝ゴミ化防止）。専用フォルダを増やさないのがポイントです。
ライフサイクル（状態遷移必須・放置禁止）
- spec化: 構想が spec に昇格したら、メモ → spec へのリンクに置換
- タスク破棄: タスクが破棄されたらメモも消える（運命共同体）
- 滞留ガード: 📝WIPメモのまま30日更新なければ破棄候補としてフラグ
- 長文化: 構想が長くなりそうなら最初から spec 直行（📝WIPメモは軽量が前提）
発動タイミング
- 明示キーワード: ユーザーが「これ残して」「決定事項にして」「構想メモ」と言った時 →
ssot-recordスキル（構想モード）で該当タスク直下に追記 - ルートα:
brainstorming/sentakuスキル終了時に spec を出力しなかった場合 →「代わりに構想をバックログ該当タスク直下に📝WIPメモとして残しますか?」と確認 - 能動検知（LLMの自律提案）は行わない（誤検知/アラート疲労回避・迷ったら出さない）。
resume-sessionが安全網
日記フォーマット
# 2026-05-31
## セッションログ (14:30)
- PostgreSQL→SQLite移行スクリプトを実装
- マイグレーションのバグ修正（NULL制約エラー）
- 詳細: 01_DECISIONS/project-a/2026-05-31_db-migration.md
- 未解決: ステージング環境での検証
## セッションログ (20:00)
- APIエンドポイントのテスト追加
- 詳細: 01_DECISIONS/project-a/2026-05-31_api-tests.md
---
セッション終了: 21:30
MOC（Map of Content）
なぜMOCが必要か
vaultが大きくなると「あの情報どこにあったっけ？」が発生する。
MOCは全トピックへの索引で、これを読めばどこに何があるかがわかる。
MOCの構造
# 全体マップ（MOC）
## Claude Code設定・運用
| トピック | 場所 | 内容 |
|---|---|---|
| Hooks設定 | 00_SYSTEM/自動化.md | 4種のフック構成 |
| セキュリティ | 00_SYSTEM/セキュリティ設定ハブ.md | コマンドガード |
## プロジェクト別
| プロジェクト | 場所 | 主な内容 |
|---|---|---|
| project-a | 01_DECISIONS/project-a/ | DB設計・API実装 |
| project-b | 01_DECISIONS/project-b/ | フロントエンド |
MOCの更新ルール
- 新しいトピックを追加した時: 必ずMOCにリンクを追加
- ファイルを移動した時: MOCのリンクを更新
- セッション開始時: Claude CodeがMOCを自動読み込み
_INDEX.mdの活用
各プロジェクトフォルダに _INDEX.md を置く：
# project-a — 決定ログ索引
| ファイル | 内容 | いつ参照するか |
|---|---|---|
| 2026-05-15_db-migration.md | DB移行 | DB設定に迷った時 |
| 2026-05-31_api-tests.md | API仕様 | テスト追加時 |
自動生成スクリプト概念:
# generate-index.sh
for file in *.md; do
[ "$file" = "_INDEX.md" ] && continue
title=$(head -1 "$file" | sed 's/# //')
echo "| $file | $title | 【要更新】 |" >> _INDEX.md
done
ハンドオフドキュメント
セッション終了時に次のセッションへ引き継ぐメモ：
# handoff.md
## 直前のセッション（2026-05-31 21:30終了）
- 実施: PostgreSQL→SQLite移行
- コミット: feat: DB migration to SQLite
- 未完: ステージング環境テスト
## 次のセッションでやること
1. ステージング環境でマイグレーション検証
2. CIパイプラインの更新
3. README.mdのDB設定手順を更新
record-ssot スキルによる自動記録
Claude Code に record-ssot スキルを組み込むと、「記録して」の一言で SSOT への記録・日記追記・ガイド転記まで自動化できる。
フロー
「記録して」と言う
↓
GLM が内容を分析して振り分け先を判定
↓
📋 判定結果を一画面で提示（転記先も含む）
↓
「yes」で承認
↓
SSOT ファイル作成 → _INDEX.md 追記 → 日記追記
→ ガイド転記（承認済みなら追加確認なし）→ push
判定結果の画面例
📋 記録先の判定結果
📁 メイン: 01_DECISIONS/ssot-guide/2026-05-31_テスト構成.md
📅 日記追記: あり（10_DAILY/2026-05-31.md）
📖 ガイド転記: あり → ssot-guide「09_ガイドサイト構築.md」
└ 追記内容: test_convert.py の9クラス構成・テスト保護パターン
🏷️ タグ: #テスト #品質管理
この振り分けでよいですか？[yes/修正指示]
「yes」と答えるだけで、ファイル作成・日記追記・ガイド転記・push まで一括実行される。
転記先と追記概要はフェーズ2の判定画面に統合されているため、別途「転記案を見せますか？」の確認は発生しない。
外部公開コンテンツ管理（20_PUBLISHING）
20_PUBLISHING/
├── _INDEX.md ← 全記事の状態管理
├── zenn/
│ └── 2026-05-31_title.md
└── note/
└── 2026-05-15_title.md
# _INDEX.md
| タイトル | 媒体 | 状態 | URL |
|---|---|---|---|
| AI開発の知識管理 | Zenn | 公開済 | https://... |
| LLMルーティング設計 | note | 下書き | - |
並行セッション運用（タスク占有ボード）
複数ウィンドウで Claude Code セッションを並行稼働する際、handoff「次タスク候補」と SessionStart バックログ通知が全セッション共通で出るため、別窓が着手済みのタスクに重複着手する問題を防ぐ仕組み。
仕組み（active-sessions.md 拡張）
00_SYSTEM/active-sessions.md は元来「共通ファイル競合回避ボード」だったが、冒頭に 🟢進行中タスク セクションを新設し「タスク占有ボード」を兼ねる。
| 要素 | 役割 |
|---|---|
| 🟢進行中タスク表 | タスク占有の唯一の真実（タスク名・窓・開始・方針） |
| resume-session | タスク選択時に CC が自動で🟢表へ追加 → 即push |
| new-session | ✅で占有解放（タスクはバックログに戻り候補復活） |
| SessionStart hook | 🟢進行中タスク一覧を冒頭表示 |
| CLAUDE.md | 着手前 soft警告ルール（ブロックせずユーザー判断） |
ライフサイクル
開始(resume): タスク選択 → CC自動🟢追加 → 即push
↓
進行(他窓): SessionStartに🟢一覧表示 → 着手前 soft警告
↓
終了(new): ✅で占有解放 → handoffに前回占有タスク記録
↓
復帰(resume): 「続きやる？」で再🟢 or 解放
設計判断
- soft警告（強制ブロックなし）: 人間が判断
- 宣言の手間ゼロ: タスク選択の瞬間に CC が自動で🟢追加
- 原則解放＋復帰時再宣言: セッション閉じたら占有解放で枯死ロック回避
詳細: docs/superpowers/specs/2026-06-23-task-occupancy-board-design.md