Request を contract にし、verified code に変える。
CafeKit は重要な truth を chat の外に置きます。Assistant は contract を先に書き、approved task packet を実装し、evidence で prove して state を sync します。
人が変更を依頼します。
Scope、requirements、design、tasks が durable files になります。
Assistant が approved task packet を 1 つ実装します。
Real commands と runtime proof で結果を確認します。
別 pass で compliance と risk を確認します。
Evidence がある時だけ state を進めます。
シンプルに言うと#
Spec-driven development とは、chat ではなく spec が主導する ということです。
通常の AI coding では、assistant が会話の記憶に頼りがちです。それは壊れやすい状態です。Request が間違って要約されたり、scope がずれたり、次の session が decision の理由を知らないまま進むことがあります。
CafeKit は中心を変えます。Code を変更する前に、作業内容を specs/<feature>/ に書きます。この folder が human、assistant、reviewer、future sessions の shared contract になります。
Code 変更前に何を作るかを書きます。
Approved task boundary だけを実装します。
Commands を実行し exact evidence を記録します。
Proof 後に spec.json と task markdown を更新します。
Assistant が信頼すべきもの#
Assistant は durable repo artifacts を先に信頼します。
Machine state: phase、scope lock、task registry、approvals。
User-visible behavior と acceptance criteria。
Source-backed findings と decisions。
Architecture、contracts、data flow、invariants。
Files、steps、criteria、evidence を持つ implementation packet。
重要なのは file 数が増えることではありません。各 file が別の質問に答えることです。
| Artifact | 答える質問 |
|---|---|
requirements.md | Product は何をするべきか? |
research.md | Source-backed facts や decisions は何か? |
design.md | System はどう設計されるべきか? |
tasks/task-R*.md | 今 approved されている implementation unit は何か? |
spec.json | Feature の machine-readable state は何か? |
日常の作業ルール#
意味のある feature では、この rule を使います。
Request が specs に入れるほど明確でない場合だけ、先に /hapo:brainstorm を使います。Delivery path 自体はここから始まります。
- Goal が contract にできるほど明確なら
/hapo:specsを実行する。 - Approved task packets がない spec では develop しない。
/hapo:developは task packet 1 つずつ実行する。/hapo:testで verify し、/hapo:code-reviewで review する。- Proof がある時だけ
/hapo:syncを使う。Drift repair には/hapo:sync audit <feature>を使う。
Full SDD path を使う場面#
Product behavior を変える、複数 file に触れる、runtime boundary をまたぐ、data/auth/package contracts を変える、users に影響する、review evidence が必要、または他の assistant や teammate に handoff する可能性がある場合は full path を使います。
小さな copy edit や明確な one-line fix では full spec flow は重いことがあります。それでも習慣は同じです。Boundary を明確にし、その boundary だけを変更し、結果を verify し、hidden scope growth を避けます。
次に読むもの#
Core workflow で command path 全体を確認してください。spec.json、task packets、validation、readiness の詳細 rules が必要なら Spec lifecycle を読んでください。