Architecture Decision Records¶
決まったことはここにある。 他のドキュメントは「いまどうなっているか」を書く場所で、 「なぜそう決めたか」と「何を捨てたか」はここに置く。
なぜ ADR を導入したか¶
docs/design.md は決定を「追記（日付）」で積む形だった。これが一度壊れた。
§4.4 は「固定枠 8 本を人が一度だけ信頼する（案 B）」と書き、§6 の決定表もそう記録している。
だが 2026-08-18 の追記が案 A（起動前の自動書き込み）へ切り替えており、実装もそうなっている。
本文と決定表は古いまま残り、bin/ccs が CCS_SCRATCH_SLOTS に添えたコメントも
「毎回新しいディレクトリを作ると trust ダイアログが毎回出る」という古い理由を語り続けていた。
結果として、2026-08-20 に「8 枠は trust ダイアログ回避のため」という前提で設計を議論し、 その前提が既に 2 日前に無効化されていたことに気づくまで時間を使った（→ ADR-0001）。
追記で上書きする形式は、読む人が最新の追記まで辿り着けたときにしか機能しない。 決定は 1 ファイル 1 決定にして、覆ったら Superseded と明記する。
書き方¶
NNNN-<短い-kebab-case>.md。番号は連番、欠番は作らない。
# ADR-NNNN: <決定を言い切る一文>
- **状態**: Accepted | Superseded by ADR-NNNN | Deprecated
- **日付**: YYYY-MM-DD
- **関連**: #<issue>, ADR-NNNN, docs/xxx.md §N
## 文脈
何に困っていたか。制約は何か。
## 決定
何を決めたか。言い切る。
## 根拠
なぜそう決めたか。**実測があるなら再現できる形で載せる。**
## 捨てた案
検討して採らなかったものと、その理由。後から掘り返さないために書く。
## 影響
コード・ドキュメント・運用に何が起きるか。
規律¶
- 決定を覆すときは、古い ADR を消さない。 状態を
Superseded by ADR-NNNNに変え、 新しい ADR に「何を覆したか」を書く。履歴が残らないと同じ議論を繰り返す docs/design.mdに決定を書かない。 design.md は現状の説明に徹し、決定は ADR を参照する- コードのコメントが設計判断を語るときは、ADR 番号を添える。 理由が変わったとき、 コメントだけ取り残されるのを防ぐ
一覧¶
| # | 決定 | 状態 | 日付 |
|---|---|---|---|
| 0001 | 使い捨て作業枠は固定 8 枠をやめ、セッションごとに一意なディレクトリを作る | Accepted | 2026-08-20 |
| 0002 | 同一性は workspaceId と sessionId で表し、名前は表示用のラベルに落とす |
Accepted | 2026-08-21 |
| 0003 | worktree はリポジトリ配下の .worktrees/ に置き、素性は git から引く |
Accepted | 2026-08-26 |
| 0004 | 作業枠の成果物は ~/ghq/local/<owner>/<name> へ昇格する。根治（枠に CLAUDE.md）を先に置き、外部への作成は ccs がやらない |
Accepted（未決 2） | 2026-08-31 |