intent-planner

README: 日本語 | English

AI に「いい感じにやっておいて」とお願いすると、ひとつひとつは悪くないのに、全体としてだんだん思っていたのと違う方向へ進んでいく——そんな経験はないでしょうか。

intent-planner は、AI に作業を頼む前に、「何をしたいのか」「これだけは外したくない」を AI といっしょに言葉にしておくための道具です。先に向きを合わせておくと、途中で少しずつズレていくのを防げます。

特に向いているのは、設計のずれや統合ミスが大きな損失につながり、手戻りにも多くの時間がかかる高リスクな案件です。反対に、短い試作や vibe coding で十分な小さな変更には、この工程が過剰になることもあります。その場合は、作業単位（packet）から直接実装する direct 経路を選ぶか、intent-planner 自体を省略できます。案件に必要な分だけ使うのが基本です。

やることはシンプルで、頭の中にあるぼんやりした考えを、AI が質問してくれるのに答えながら整理していくだけ。むずかしい知識はいりません。

導入しても増えるのは、いくつかのコマンドと .intent/ というフォルダ1つだけ。あなたのファイルやコードを勝手に書き換えることはありません（書き込むのは .intent/ の中のメモだけです）。

📌 技術的には、intent-planner は **AI コーディングエージェント（Claude Code / Codex）向けの「仕様作成前の Steering（舵取り）レイヤー」**です。仕様を書く一段手前で、プロジェクト全体に関わる意図と設計方針を整理し、実装中も参照できる形で残します。エンジニア向けの詳しい説明は後半にあります。

自分はどの使い方かな？

使い方は大きく3通り。上から順にだんだん技術寄りになっていくので、自分に近いところから読んでください。

| こんな人 | 使い方 | 読む章 | |---|---|---| | 📝 コードは書かない（企画・調査・文書づくり） | 考えを整理して、読める成果物（記事の構成案・手順書・調査メモなど）を作る道具として | ① コードを書かない人へ | | 💻 AI に実装を頼む（ふだんの開発） | 仕様を書く手前に1段はさんで、意図を整えてから実装に渡す | ② AI に実装を頼むとき（Pre-spec Steering Layer） | | 🔁 まるごと自動で回したい | 意図→実装→ふりかえりのサイクルを、外側のループ（/loop など）で自走させる | ③ まるごと自動で回す（full IDD） | | 🧭 何を作るかを決める・企画する（職種を問わず1人で製品や機能を考える人） | 実装の細部に入らず、意図の問い・読み手向けの一枚もの・進捗の俯瞰から入る | 製品・企画を決める人へ |

各機能の細かい使い方（モード・コマンド一覧・enforcement・drift-watch など）は docs/guide.md にまとめてあります。この README は「自分の状況でどう始めるか」に絞っています。

はじめに：3分でわかる全体像

intent-planner は、AI に実装を頼む前に意図を整理し、実装のあとに学びを文書へ戻す、ひとめぐりのループです。

①意図を整理する          ②実装に渡す        ③実装する         ④学びを戻す
discover → compass        export            （AI が実装）       writeback
  → packets                                                    → improve
        └─────────── 迷ったら status（現在地と次の一手を1つ教える）───────────┘

各ステップの成果物は .intent/ フォルダの中の Markdown です。レビューしてから次へ進めます。迷ったら /intent-status が、いまどこにいて次に何をすればいいかを1つだけ教えてくれます。

どこから始めるか（この2択）:

• やりたいことが言える → /intent-discover（意図の整理から始める）
• 途中から再開する・状況が分からない → /intent-status（現在地と次の一手を1つ案内）

必要なもの

• Claude Code / Codex（--agent で選択）
• Node.js（インストーラの実行に使うだけ。動作時の依存はゼロ）
• cc-sdd や OpenSpec（任意。実装に渡す先として使う場合）

インストール

# プロジェクトのルートで（既定は Claude Code）
npx intent-planner

# Codex を使う場合
npx intent-planner --agent codex

# 何が起きるか先に確認したいとき
npx intent-planner --dry-run

実行するとこう出ます（実際の出力の抜粋）:

新規配置しました (149):

配置エージェント: claude
  skill: .claude/skills/intent-*/
  ルート doc: CLAUDE.md を配置しました。

次にやること:
  1. Claude Code を開く
  2. プロンプトに /intent-discover と入力して実行する（意図の詰めがここから始まります）

⏱ はじめての方へ: インストールから「実装に渡す下書き」ができるまでを実際の画面つきで一巡する 10分ウォークスルー があります。

導入すると、使う AI に合わせて「使い方を教える薄い入口」（Claude Code なら CLAUDE.md、Codex なら AGENTS.md）と、雛形の .intent/ フォルダが置かれます。既存の CLAUDE.md / AGENTS.md があっても上書きはせず、確認のうえ非破壊で追記します（既存内容は変更しません。Claude Code は別ファイルへ本体を置いて参照1行を、Codex は末尾に節を足します）。非対話環境では追記を見送り、--yes で同意を前渡しできます。詳しいオプションは docs/guide.md のインストール節を参照してください。

term-drift 0.3.3 は、intent-planner がバージョンを固定して依存する npm パッケージで、標準で導入されます。通常のセットアップでは、選択したエージェントの情報を term-drift の公式 installer に渡し、対象リポジトリの ./.term-drift/ と専用スキルをプロジェクト内に配置します。旧オプション --with-term-drift も既存スクリプトとの互換性のため受け付けますが、指定しなくても配置されます。

導入状態は not-installed（未導入）、ready（利用可能）、inconsistent（一部だけ導入されている、または内容に不整合がある）のいずれかで表示されます。inconsistent はさらに、安全に不足分だけを追加できる additive-compatible、公式 update を試せる既知の状態である update-attemptable、自動処理しない blocked に分かれます。install-failed は、その回の導入処理が失敗したことを示す結果であり、現在の配置状態とは別に表示されます。

新規導入と安全な追加は公式 installer、対応済みの旧版からの更新は公式 update に任せます。ready なら再実行せず、未知の版や将来の版にも自動追随しません。また、intent-planner が term-drift 所有のファイルを独自に修復したり、上書きしたりすることもありません。term-drift 0.3.3 では、利用者が範囲を明示して任せた場合に、エージェントが低リスクな言い換えを判断できます。適用用の記録には、人の承認か委任された判断か、その判断日時と委任範囲が残ります。意味が確定できない箇所や、法務・セキュリティ・公開 API・実行時の挙動に関わる箇所は引き続き人へ確認します。状態が ready になったら、選択したエージェントの term-drift 専用スキルから本格的な用語点検を始められます。

旧バージョンからアップグレードする場合は docs/migration.md（移行ガイド）を参照してください。既存の .intent/ の成果物は上書きされない一方で、新しく入った仕組み（履歴の退避先・検索タグ）を既存プロジェクトへ取り込む手順を、Claude Code / Codex ごとに説明しています。

compass を1項目1ファイルで保存する新形式への移行は任意です。移行しなくても、従来の単一ファイル形式を引き続き読み取れます。

コードを書くエンジニアの方へ: 意図を整理したあとは、/intent-export-cc-sdd、/intent-export-openspec、/intent-export-speckit のいずれかで、cc-sdd、OpenSpec、GitHub Spec Kit 用の下書きを作り、仕様駆動の実装フローへ進むのがおすすめです。仕様書が残っておらずコードしかない場合は、/intent-from-code を使うと、コードから意図の候補を「推測」と明示したうえで整理できます。

① コードを書かない人へ

intent-planner はもともと AI でプログラムを作る人向けですが、頭の中の考えを整理して「読める成果物」にまとめる道具としても使えます。記事の構成を練る、調べたことをまとめる、企画書をつくる——そんなときの道筋です。

使い方はかんたん。/intent-discover を実行すると、AI が「何をしたいんですか？」と質問してくれるので、それに答えていくだけ。AI のほうで「これは文書づくりですね」と見て、文章をまとめる進め方（non-code モード）に切り替えてくれます。案件の種類（企画書・調査まとめ・記事の構成・イベント計画など）に合った質問セット（質問パック）が候補として提案されることもあり、使うかどうかはあなたが選べます。

/intent-discover    ← したいこと・考えたいことを整理（AI が質問してくれる）
  → /intent-compass ← 「これは外したくない」という方針を決める
  → /intent-to-spec ← 記事の構成案・手順書・調査メモなど、読める形にまとめる

• 最後の /intent-to-spec で、整理した内容を1本の読める文書にまとめてくれます。はっきりした根拠のない部分には「推測」の印が付くので、AI が勝手に話を盛っていないか見分けられます。
• できあがった文書は .intent/nl-spec/ というフォルダに入ります。

コードを書かない人は、ここまでで十分です。この先の章はプログラムを作る人向けなので、読み飛ばして大丈夫です。

② AI に実装を頼むとき（Pre-spec Steering Layer）

ここからはエンジニア向けです。intent-planner のいちばん基本の使い方は、仕様（spec）を書く手前に1段だけ挟んで、意図を整理してから実装に渡すこと。整理した意図は、そのまま cc-sdd や OpenSpec の spec 駆動フローへ引き継げます。

ここで決めた基準は、実装中も AI が参照する判断材料になります。

進め方

各ステップの成果物をレビューしながら、この順に進めます。

/intent-discover   →  /intent-compass  →  /intent-packets  →  /intent-export-cc-sdd
（全体像を整理）       （守るべき基準）     （作業単位に分解）    （実装ツールへ引き継ぎ）

1. /intent-discover — 課題やアイデアについて AI が質問し、意図の全体像を組み立てます。まだ解決策を絞り込めない案件では、仮説・反例・別の問題設定を暫定案として示し、次の compass で人が判断の範囲を決めます。
2. /intent-compass — 「目指す姿」「進んではいけない方向」「壊してはいけない不変則」などの判断基準を作ります。この基準は、実装中も AI に渡されます。
3. /intent-packets — 実装に渡せる作業単位（packet）に分けます。最初に着手すべき単位を理由つきで1つ薦めてくれます。次に進む出口（実装方法）も、そのリポジトリで実際に使えるツール（cc-sdd / OpenSpec / Spec Kit のどれが導入済みか）を見て、導入済みを先に・未導入は「導入が要る」と添えて並べます。未導入でも候補から消えないので、後から入れる選択もできます。
4. /intent-export-cc-sdd（または /intent-export-openspec・/intent-export-speckit）— 選んだ作業単位を実装ツールの下書きに変換します。下書きには受入基準の材料（期待挙動・受入をどう測るか）が含まれ、下流の要件生成が薄くならないようになっています。

そのあとは cc-sdd / OpenSpec の spec フロー（requirements → design → tasks → 実装）を回します。intent-planner が作るのは下書きまでで、spec の本体は実装ツールが生成し、各フェーズであなたがレビューします。

実装中は .intent/execution-contract.md が短い共通契約になります。AI は合意済みの境界内では実装方法を自由に選び、設計を越える良い案を見つけたときだけ、黙って捨てたり勝手に実装したりせず「現設計を維持／設計変更を承認／次の作業単位へ送る」の判断材料を提示して待ちます。同じ契約が direct・cc-sdd・OpenSpec・Spec Kit・writeback に渡ります。

作業単位がデータベースの設計を含むときは、/intent-db-design が意図・不変則・既存スキーマを読み合わせて、テーブル定義や制約・インデックスの叩き台を（あくまで下流ツールに渡す前の読み物として）起こします。要件そのものではなく設計の当たりをつけるためのもので、起動はあなたが手動で行います。

このとき何がうれしいのか（Before / After）

曖昧な依頼1行が、intent-planner を通すとどう具体化されるかの例です（題材: ログイン機能）。

Before — AI への依頼はこれだけ:

ログイン機能をいい感じに作って

「いい感じ」の解釈は AI 任せになり、独自のパスワード認証を生やす・既存の認証基盤と合わない実装に進むなど、その場しのぎに流れがちです。

After — discover → compass → packets を通すと、同じ依頼がこうなります:

• ゴール（計測基準つき）: 初回ユーザーが2分以内にログインを完了できる（開始〜ダッシュボード表示で計測）
• 不変則（守ること）: 既存の OAuth provider（Google / GitHub）との互換性を壊さない
• 進んではいけない方向: 独自のパスワード認証を追加しない
• 作業単位:
  1. P1: OAuth callback の E2E — 一番細い経路を最初に貫通させる
  2. P2: エラー状態と再試行 UI
  3. P3: 監査ログ

最初に薦められるのは P1。一番細い経路を先に通すことで、最大の不確実性（リダイレクト設定・セッション管理）を最初に潰せるからです。

このゴール・不変則・進んではいけない方向が、P2 以降の実装でも AI に毎回渡り続けるので、「独自認証を生やさない」「既存 provider を壊さない」という基準が効き続けます。

実装が終わったら（育て続ける）

「作って終わり」にしないために、実装の学びを意図の文書へ戻します。

• /intent-writeback — 実装で分かったこと（新しく決まったこと・不変則の違反・暗黙の挙動）を記録し、あなたが承認した分だけ文書へ反映します。
• リリース後は L1 の 成果の物さし:（利用者価値が出たと分かる条件）に照らして結果も記録できます。工程の完了と利用者成果は別に扱い、結果は人の承認後だけ L1 に反映されます。記入から結果表示までの手順は docs/guide.md にまとめています。
• /intent-improve — 数件こなした節目に、文書と実装のズレをまとめて検出して直します。
• /intent-validate — 意図の文書どうしの矛盾・カバレッジ漏れ・境界のずれを、深刻度を付けて読み取り専用で報告します。修正案は示しますが、ファイルを勝手に書き換えません。実装ツールへ渡す前に一度実行しておくと安心です。project-local な term-drift 配置物がある場合も、/intent-validate 自身は用語や health を独自判定せず、外部コマンドも起動しません。代わりに、利用者へ通常 installer の npx intent-planner . --agent <選択中のagent> --dry-run でhealthを確認するよう案内し、ready の確認後だけ term-drift 専用 skill へ進みます。ready になったら、term-drift 専用 skill から本格的な用語点検を始められます。

これで .intent/ は実装の現実と同期し続ける、生きた判断基準になります。

③ まるごと自動で回す（full IDD）

②では人が /intent-status を見て次の一手を毎回手で進めました。代わりに、/loop のような外側のループに駆動を委ねると、意図→実装→書き戻しのサイクル全体を自走させられます。これが intent-planner を Intent Driven Development（IDD） として一周まるごと回す使い方です。

intent-planner 自身は「いま何工程目か（state）」を記録しますが、それを自動で次へ進める仕組み（状態機械）は内蔵していません。だから駆動を外に出せます。

/loop /intent-status
  → status が出す「次の一手」を外側のループが拾い、
    次の作業単位の export → 実装 → writeback まで進めて、
    また status に戻る — これを繰り返す

②との違いは駆動を誰が握るかだけです。どちらでも、次に何を作るかを決めているのは Intent（整理した意図と、status が出す「次の一手」）です。

新しい意図を足す（loop に依頼を渡す）

/loop は依頼を外から流し込む仕組みではなく、同じコマンドを繰り返し叩くだけです。では「次に何を作るか（＝依頼）」はどこから来るのか — .intent/packets/ に並んでいる packet そのものが依頼です。loop の /intent-status は毎周そこを読み、まだ実装されていない packet を「次の一手」として拾います。

だから、自走中に新しいやりたいことを足すには、packet を1つ増やせば済みます。具体的には、loop とは別のセッションで、人間が運転して足します:

別セッション（人間が運転）: /intent-discover → /intent-compass → /intent-packets
   → .intent/packets/ に新しい packet が増える（＝依頼をファイルとして置く）

回りっぱなしの loop セッション: 次の周の /intent-status がその packet を拾う
   → export → 実装 → writeback まで自走する

つまり、別のセッションで packet を作れば、そのファイルが loop への新しい依頼になります。両方のセッションが同じリポジトリの .intent/ を読むため、loop を止めなくても依頼を受け渡せます。

意図を追加する操作（discover / compass / packets）を人が別のセッションで行うのは、これらが文書を書き換え、人の承認を必要とするからです。loop は動かしたままにして、新しい意図を確認する作業だけを別のセッションで行います。

⚠️ 自走させるときの代償（必ず把握してください）

文書を書き換えるコマンド（discover / compass / packets / writeback / improve / export）は、意図的に人間の承認を前提にしています。無監視で走り続ける開発（vibe coding）への歯止めです。/loop で承認を飛ばすと、速さと引き換えに次を失います:

• ズレに気づく機会 — 各段で「意図とズレている」と気づく機会が減る
• 文書の保護 — 誤った学びがそのまま意図文書に反映されうる
• 重い分岐のレビュー — 人が確定すべき問いを承認なしで埋めると、推測が確定として固定されうる

おすすめは、人の確認と自動化を組み合わせる方法です。 「実装→テスト→修正」は /loop に任せ、compass の確定、packet の分解、writeback の承認、重要な判断の確定では人が確認します。読み取り専用のコマンド（status / validate / overview）は承認なしで実行できるため、/loop の中でも安全に判断材料を出し続けられます。すべてを無確認で進めるのではなく、影響の大きい判断に人の確認を集中させるのが、速さと安全を両立させる使い方です。

自走の仕組みと注意点は docs/guide.md の「自動で回す」節に、理論的背景は docs/theory.md の「状態は持つが、状態機械は持たない」節にまとめています。

こんなときに

具体的な状況からも入れます。

| 状況 | intent-planner がやること | 使い方 | |---|---|---| | 文書・調査・企画をまとめたい（コードを書かない） | 意図を整理し、読める成果物を直接生成する | ① | | 新規プロダクト・機能を AI 主導で作り始めたい | 作りたいものの意図と基準を実装前に言語化し、最初の1行から舵を効かせる | ② | | PoC・個人開発を1人で作りたい | 詰めの問い（計測できる成功基準・最小貫通・仮説と反証条件）を入口で選べる | ② | | 大規模リファクタを頼みたい | 「正しく動くが設計意図からズレる」変更を防ぐ基準を先に作る | ② | | レガシーで仕様が分からない | 観測できる振る舞いから意図を逆算して文書化する | ② | | 稼働中システムに機能追加したい | 既存への影響を踏まえた追加単位に分解する | ② | | 計画から実装・書き戻しまで自走させたい | 外側のループに駆動を委ね、人は効く一点だけ承認する | ③ |

安心して使うために

• アプリのコードは変更しません。書くのは .intent/ の中の Markdown だけです（writeback / improve も承認した分しか反映しません）。
• 既存ファイルは上書きしません（--force を指定したときを除く）。まず --dry-run で確認できます。
• 検査系（enforcement / drift-watch）は既定 off で、設定しない限り動作は何も変わりません。git フックは --enforce を明示したときだけ配置します。
• 動作時の依存ゼロ（Node 標準モジュールのみ）。常駐プロセスも、外部サービスへの送信もありません。

製品・企画を決める人へ

職種を問わず、製品や機能の「何を作るか」を考える人向けの使い方です。実装の細部に入らず、意図を明確にし、読み手へ伝えるための機能だけを使えます。

• 意図を問いで詰める — /intent-discover に答えていくと、「誰の何の問題か」「うまくいったと何で分かるか」といった、企画の芯を言葉にする問いが出ます。ここだけでも、頭の中の構想が読める形に落ちます。
• 読み手向けの文書にまとめる — /intent-to-spec では、関係者向けの一枚もの、定例報告、意思決定メモを作れます。一枚ものと定例報告は結論を先に示し、意思決定メモは選択肢の採否と理由を比較表で示します。通常の文書では、詳しさを「概要 / 標準 / 詳細」から選べます。指定しなければ、生成前に一度だけ確認されます。
• 変更の説明を作る — /intent-release-note では、利用者への影響を先に示す顧客向けの変更履歴や、変更理由・レビューの要点・コミットと意図の対応をまとめた PR 説明の下書きを作れます。GitHub への書き込みは行わないため、貼り付けは自分で行います。
• 散らばった情報を見渡す — /intent-overview では、未決事項や承認待ちを集めた「判断待ちの一覧」、作業順と依存関係を示す「ロードマップ」、意図や作業順を表す Mermaid 図、並行作業の担当を示す「割当ビュー」を作れます。また、次のセッションへ現在地・残作業・参照すべき正本・注意点・リポジトリの状態を渡す「引き継ぎブリーフ」も作れます。これは .intent/ の状態から生成する一時的な文書で、会話ログは読みません。
• 作りたい順を伝える — /intent-packets の計画書には、「まずログイン、次に通知」のような作業のまとまりと優先順位を書ける「工程計画」があります。記入すると、その順序を考慮して最初の作業を案内します。ただし、依存関係とは別に扱い、順序を強制はしません。
• 全体を俯瞰する — いま何が決まっていて何が未決かを /intent-status が1つの「次の一手」として示します。

ここで整理した意図は、そのままエンジニアの仕様駆動フローへ渡すこともできます。

外部ツールとつなぐ（Notion / Jira / Slack など）

「Notion 上の PRD と intent を行き来する」「まとめた一枚ものを Slack に貼る」といった連携は、追加のインストールや設定なしで、ふだん使っているエージェント（Claude Code / Codex）の読み書きだけで成り立ちます。

• できること（読みは双方向）: 外部ツールの文書をエージェントに読ませて intent へ渡す（Notion の PRD・Jira の issue・散らかった断片メモ → /intent-from-spec や /intent-discover）／intent がまとめた Markdown を人やエージェントが外部へ貼る（/intent-to-spec・/intent-overview の成果物 → Notion / Slack）。
• やらないこと（書き込みの双方向同期）: intent と外部ツールを自動で双方向同期はしません（恒久的にやりません）。出所の管理と衝突の解決を製品が背負わないためです。連携はあくまで「人かエージェントが読んで渡す・貼る」片方向の2本に留めます。
• 貼る前にひとつ確認: 外部サービスへ内容を貼ると、あとで消しても控えや索引に残ることがあります。機密や個人情報が混じっていないかを貼る前に確かめてください。

具体的な手順（Notion → from-spec、一枚もの → Slack 貼り付けの例）と、なぜ双方向同期をやらないのかは docs/integration.md にまとめてあります。

もっと知りたい

• ⏱ まず動かして掴みたい — インストールから実装直前までを実際の画面つきで一巡 → docs/walkthrough.md
• 各機能の使い方 — モード・コマンド逐条・Decision の関係判断と見直し・ファイル構成・enforcement・drift-watch・造語管理・制約叩き台など → docs/guide.md
• 観点別レビュー — 深掘りを選んだ案件だけ、製品・必要時の進行・利用体験を決める責任範囲から仕様の抜けと食い違いを確認します → 使い方と適用条件
• 体験設計のフレーム候補 — 案件に合う場合だけ確立したフレームを理由付きで提示し、人が採用した場合だけ .intent/nl-spec/design-frame-<frame-id>.md に派生の下書きを作ります。画像・図の生成、アナリティクスによる実測、体験段階、数値の優先度、日付コミット、進捗率は対象外です → 体験設計のフレーム候補
• 外部ツールとの連携 — Notion / Jira / Slack と intent を片方向でつなぐパターン集（双方向同期をやらない理由つき） → docs/integration.md
• なぜこの手順なのか — 要求工学・ソフトウェアアーキテクチャ研究との対応、参考文献つき → docs/theory.md
• 並行 AI セッションと領域ガバナンス — 判断基準（compass）と意図ツリーが大きくなっても、実体は割らず「所有権と処理範囲」だけを領域ごとに委ねる考え方（宣言型・止めない・宣言が無ければ従来どおり）。使い方は docs/guide.md の「領域ガバナンス」節、背景は docs/theory.md の「大規模開発で意図を維持する」節
• すでに造語で埋まったプロジェクトを直したい — 文書の中の怪しい用語を見つけ、あなたが1語ずつ承認した言い換えだけで直す独立ツール（intent-planner が無くても単体で使えます） → term-drift

理論を知らなくても、フローに沿って質問に答えていけば必要な成果物が埋まるように設計しています。docs は「もう一段くわしく知りたくなったとき」の参照用です。

ライセンス

MIT © Yoshishige Tsuji

本プロジェクトの開発には cc-sdd（MIT, © 2025 gotalab）由来のツーリングを使用しています。配布物（npm パッケージおよび本リポジトリの templates/ 等）に cc-sdd 由来のファイルは含まれません。