intent-planner

README: 日本語 | English

デモ動画 · 10分ウォークスルー · 詳しいガイド

AIに作業を頼んだとき、個々の変更は悪くないのに、全体が少しずつ思っていた方向から外れることがあります。intent-plannerは、作業の前に「何を実現したいか」「何を壊してはいけないか」を整理し、仕様作成や実装へ渡すための軽量な計画レイヤーです。

企画書、調査、文書づくりにも使えます。Claude Code、Codex、Gemini CLIに対応し、整理した内容はcc-sdd、OpenSpec、Spec Kitへ渡すか、そのまま小さな実装単位として使えます。

特に、設計のずれや手戻りが大きな損失になる高リスクな案件に向いています。短い試作やvibe codingで十分な変更には過剰になり得るため、作業単位から直接進むdirect経路を使うか、intent-plannerを省略してください。

どんなときに使うか

やりたいこと	使い方
企画書・調査メモ・手順書をまとめる	質問に答えながら意図を整理し、読める文書へ変換する
AIに開発を頼む	仕様を書く前に、目的・判断基準・実装単位を揃える
既存コードの意図を復元する	コードから候補を抽出し、推測であることを明示して確認する
実装後のずれを直す	実装で分かったことを記録し、承認した内容だけ計画へ戻す

専門的な分類名や案件種別を先に選ぶ必要はありません。目的、作りたい成果物、手元の資料、次に行いたい判断のどれか一つを伝えれば始められます。

コードを書かない場合

企画書、記事の構成、調査結果、業務手順なども、同じように意図を整理できます。AIが目的・読み手・必要な判断を確認し、最後にintent-to-specで1本の読める文書へまとめます。根拠が確定していない部分は推測として区別されます。

AIに実装を頼む場合

仕様を書く前に、解決したい問題と実装中の判断基準を揃えます。その後は次のいずれかへ進めます。

• cc-sdd、OpenSpec、Spec Kit向けの下書きを作る
• 十分に小さく明確な作業単位なら、direct経路で実装へ進む

intent-plannerは下書きと判断基準までを担います。下流ツールの仕様作成や実装を自動的に開始せず、その状態も管理しません。

何を作るか考える場合

実装方法が決まっていなくても使えます。誰のどんな問題を解くか、成功を何で判断するか、今回決めないことは何かを先に整理します。画面設計やサービス設計などの専門的な観点は、案件に合うときだけ候補として提示され、採用するかは利用者が決めます。

たとえば「サブスクリプションの解約問い合わせを減らしたい」という相談なら、同じ要望を複数の観点から見ます。

観点	出てくる問い・助言の例
PdM（製品を決める観点）	問い合わせの原因には根拠があるか。誰のどの状況を改善するか。成功を問い合わせ件数、完了率、再契約率のどれで見るか。解約ボタン追加以外の選択肢はあるか。
サービスデザイナー（利用体験を設計する観点）	解約を考え始めてから完了後までに、どの接点・待ち・引き継ぎがあるか。画面の裏でどの担当者や処理が支えるか。失敗、離脱、再開をどう扱うか。
画面を設計する観点	重要情報をどの順で見せるか。通常時だけでなく、読込中・失敗・権限不足・完了をどう伝えるか。次に取れる行動が明確か。
技術の定石	二重操作でも処理が重複しないか。認可と監査記録をどう守るか。外部決済の失敗や再試行、データ移行、回帰テストをどう扱うか。

これらは職種を演じて結論を決める仕組みではありません。案件に合う観点と定石だけを候補にし、根拠のない回答は未確認のまま、人が採用した内容だけを計画へ入れます。利用できる観点・フレーム・定石の一覧はガイドにあります。

自動実行と組み合わせる場合

内側の「実装→テスト→修正」を別の自動実行に任せることはできます。ただし、目的・判断基準・作業範囲の確定と、実装後の学びの反映には人の確認を残すのが基本です。読むだけの状況確認や検証は、自動実行中にも利用できます。

5分で一巡する

intent-plan（次の4段階を一続きに進める）
意図を整理する          判断基準を揃える       作業単位に分ける       仕様作成へ渡す
discover        →       compass       →       packets       →       export

たとえば「ECサイトに注文キャンセルを追加したい。返金事故は避けたい」と伝えます。AIが結果を左右する点だけを確認し、次を作ります。

1. .intent/intent-tree.md — 解決したい問題と目指す結果
2. .intent/intent-compass.md — 実装中も守る判断基準
3. .intent/packets/ — 実装する順番と確認方法
4. 選んだ仕様作成ツール向けの実装用下書き

ここでintent-plannerの一巡は終了です。アプリケーションコードの実装はまだ開始しません。成果物を確認してから、仕様作成または実装へ進みます。

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

• 新しく始める: intent-plan
• 途中から再開する、現在地が分からない: intent-status

開始方法はAIによって異なります。

• Claude Code: /intent-plan のようにスラッシュ付きで実行します。
• Codex / Gemini CLI: スラッシュを付けず、「intent-plan から始めて」のように自然文で依頼します。

一巡したあとも使い続ける

intent-plannerは、実装前の一回だけで終わる道具ではありません。

状況	使う機能	すること
現在地が分からない	intent-status	現在地と次の一手を1つ確認する
仕様へ渡す前	intent-validate	矛盾、抜け、範囲のずれを読むだけで点検する
実装が終わった	intent-writeback	実装で分かったことを記録し、承認分だけ計画へ戻す
節目で全体を見直す	intent-improve	計画と実装の現実を比較し、修正案を出す

実装中に意図から外れそうな兆候を記録する監視もありますが、警告だけで作業を止めません。詳しくはガイドを参照してください。

作るものと作らないもの

作るもの

• 目的と成果を階層で整理したIntent Tree
• 実装中も参照する判断基準
• 親の目的と確認方法を持つ小さな作業単位
• 仕様作成ツールや直接実装へ渡す下書き
• 実装後に得た学びの記録

作らないもの

• 利用者が確認していない推測を、確定した要求として扱うこと
• 計画中のアプリケーションコード変更
• cc-sdd、OpenSpec、Spec Kitの仕様書本体
• 人の承認を省いた無制限の自動実行
• すべての案件へ同じ重さの工程を強制すること

インストール

端末の制約に合う経路を1つ選びます。どの経路でも、導入後に使える機能は同じです。

1. npx — 最短

Node.js、npm、npxを利用できる場合:

npx intent-planner --agent codex --dry-run
npx intent-planner --agent codex

--agent は claude、codex、gemini から選べます。省略時はClaude Codeです。

2. npm — npxだけ使えない場合

Node.js、npm、npmレジストリを利用できる場合:

npm install --save-dev intent-planner
./node_modules/.bin/intent-planner --agent codex

Windowsでは最後の行を次に置き換えます。

.\node_modules\.bin\intent-planner.cmd --agent codex

3. WindowsポータブルZIP — Node.jsやnpmを使えない場合

最新のGitHub Releaseから、次の2ファイルを取得します。

• intent-planner-v<version>-win-x64-portable.zip
• 同名の .sha256 ファイル

ZIPを展開し、対象プロジェクトで同梱のコマンドを実行します。ホスト側へのNode.js、npm、npxのインストールは不要です。

<展開先>\intent-planner.cmd --agent codex --dry-run
<展開先>\intent-planner.cmd --agent codex

GitHubへのアクセスも制限されている端末では、組織で許可された方法でZIPと.sha256を別端末からコピーできます。取得後の詳しいSHA-256確認手順はガイドのポータブルZIP節にあります。

導入時の安全な既定値

• 既存の案内文書と、利用者が作った .intent/ の成果物は通常の再実行で上書きしません。
• --dry-run はファイルを書かず、予定だけを表示します。
• --force は利用者データも上書きし得るため、通常の導入では使わないでください。
• git hookやCIは、--enforce または --with-ci を指定した場合だけ追加します。

配置先、更新方法、補助ツール、全オプションはインストールの詳しい説明を参照してください。

Before / After

Before

「注文キャンセルを追加して」

このまま実装すると、キャンセル期限、発送後の扱い、返金責任が決まらないまま個別判断が積み重なります。

After

「購入者の操作ミスを救済する。発送後は自動キャンセルせず、返金処理は既存の決済契約を守る。まず未発送注文だけを対象にする」

目的、守る条件、最初の範囲が分かれ、仕様と実装を同じ基準でレビューできます。

よくある質問

小さな変更にも必要ですか？

必須ではありません。目的と影響範囲が明確で、失敗しても戻しやすい変更なら、direct経路またはintent-planner自体の省略が適切です。

既存の仕様駆動開発を置き換えますか？

置き換えません。仕様を書く前に全体の向きを揃え、選んだ仕様作成ツールへ必要な意図だけを渡します。

コードしか残っていないプロジェクトでも使えますか？

使えます。既存コードから意図の候補と根拠を取り込みますが、コードから推測した内容は人が確認するまで確定しません。

途中から再開できますか？

できます。intent-statusを使うと、既存の.intent/を読んで現在地と次の一手を案内します。

守ること

• 推測された意図は、人が確認するまで推測のまま扱います。
• 計画中はアプリケーションコードを変更しません。
• 重要な判断は、短い「OK」だけで確定したことにしません。
• 実装後の学びは、利用者が承認した範囲だけ計画へ反映します。
• ユーザー向け文書は正確さを土台にした文章で書きます。

次に読むもの

• 機能ガイド — 各機能、補助ツール、更新、外部連携の詳しい使い方
• 10分ウォークスルー — 初回導入から下書きまで
• 移行ガイド — 旧版を導入済みのプロジェクト
• 理論的背景 — intent driftをどう防ぐか
• cc-sdd連携 — 仕様駆動開発への受け渡し
• 既存コードから意図を復元する
• 画面デザインの詰めと下書き
• 体験設計のフレーム候補
• リリース後の成果を記録する

ガイドには、既存コードの読解、画面設計、サービス設計、不足する専門的な観点の補強、用語点検、実装後の書き戻しなど、必要になったときだけ使う機能もまとめています。

ライセンス

MIT