intent-engineering

intent-engineering

intent-engineering は、3 つのツール — audit_intent_spec、generate_intent_spec_scaffold、assess_retrofit_level — を公開する MCP サーバーです。MCP 対応クライアント（Claude Desktop、Cursor、Anti-Gravity）であれば、どれでもこのサーバーを使って、本番環境のエージェントに関する調査からまとめた 9 セクションの統一テンプレートに基づき、エージェントのインテント仕様をレビュー、ひな形化、トリアージできます。

エージェントの失敗のほとんどは、推論の失敗ではなく、インテントの失敗です。仕様が曖昧で、停止ルールがなく、成果が状態を装った活動になっています。このサーバーを使えば、エージェントがすでに実行されているハーネス内から、そのギャップを監査できます。推論の全容、却下した代替案、v0 で問題になる点については、docs/EXPLANATION.md に記載しています。

信頼性に関わる点を先に

• 自らを監査しますが、誤った数値と、その数値に対する誤った訂正を公表してしまいました。 2026-08-29 にファイル全体を採点した結果、標準スキルは 23/25、アンチパターンは 0 件 でした。このページでは 1 日にわたり 14/25 と記載していましたが、これは 32,356 文字のファイルの先頭 10,000 文字に対する訂正でした。元の数値が正しく、訂正のほうが誤りでした。同じ盲点が両方の結果を生みました。測定結果の全表はDogfood の結果にあります。
• 設計上、読み取り専用です。 どのツールもファイルを書き込みません。リトロフィットツールは提案するだけで、適用はしません。
• ファイルの読み取りにはガードを設けています。 初期バージョンは指定されたパスを何でも読み取れてしまい、/etc/passwd が実際の情報漏えいバグになっていました。現在はすべてのディスク読み取りを単一のガード経由にしています。このガードは、拡張子の許可リスト、シンボリックリンクの解決、ルート内への制限、サイズ上限を適用します。
• ビルド時に、よくある失敗モードを防ぎます。 SDK は安定版の v1.x 系に固定し、prepublishOnly ガードは src/ 内に console.log が 1 つでもあればビルドを失敗させます。また、変更履歴のルールとして、コードを変更する前に書面で承認を得ない限り、スコープを変更できません。
• 制限事項は隠さず明示しています。 Stdio のみ対応し、エイリアス表を文書化した独自の見出しパーサーを使用します。また、マッパーは同等のインテントを認識しますが、それを創出するものではないという限界も明記しています。

このサーバーを作った理由

問題

エンジニアリングチームは AI エージェントを信頼できる同僚のように扱いますが、エージェントはインテントの指定が不十分だと、気づかれないまま失敗します。その結果、間違った問題を解決する機能がリリースされます。そして、失敗モードは本番環境に至るまで見えません。PM はこの問題を二度経験します。仕様を書いているときと、エージェントが自信満々に的外れな成果を出したときです。エージェントに実行させる前に「この仕様を監査する」ための共通プロトコルはありません。

解決策

MCP 対応クライアント（Claude Desktop、Cursor など）から呼び出せる 3 つのツールを公開する Model Context Protocol サーバーです。audit_intent_spec は 25 項目の評価基準に照らして仕様を監査し、generate_intent_spec_scaffold は種類に応じて新しい仕様のひな形を作成し、assess_retrofit_level は古いドキュメントをリトロフィットします。npm には @swins/intent-engineering-mcp として、公式 MCP レジストリには DNS 検証済みの名前空間 com.seanwinslow/intent-engineering として公開しています。

トレードオフと決定事項

• Python ではなく TypeScript：MCP TS SDK は対応クライアント（Claude Desktop、Cursor）が最も充実しています。その代わり、Python を中心に使うデータサイエンス分野のユーザーは対象外になります。
• HTTP ではなく stdio トランスポート：v0 ではインフラが不要ですが、サーバーはプロセスに紐づくクライアントに依存します。v1 ではクラウドエージェント向けに SSE を追加する予定です。
• GitHub ハンドルの名前空間ではなく DNS 検証済みの名前空間（com.seanwinslow/*）：自分が管理するドメインにブランドの利用範囲を固定できます。そのために別個の Ed25519 キーペアと apex TXT レコードが必要で、mcp-publisher login github よりも事前の手間がかかりました。

学んだこと

MCP プロトコルは、基本的に「ラッパーを書かなくても、LLM が呼び出せるツールです」という契約です。これが腑に落ちると、サーバーは既存のスキルを薄く包むプロトコルアダプターになりました。また、別のナレッジグラフプロジェクトで開発していた OPTIONAL フィールドのパターンも、そのまま応用できました。

間違えた点こそ、より有益な教訓です。しかも、私は二度間違えました。ドッグフーディングのスコアとして23/25を公開しました。4か月後、部分的な読み取りの結果をファイル全体の評価として報告していたと思い込み、撤回して代わりに14/25を公開しました。実際の間違いは、その撤回でした。最初の評価はファイル全体を対象としており、差し替えた数値のほうが部分的な読み取りの結果だったのです。どちらの数値も公開されてしまったのは、ツールの出力から、評価した文書の範囲がわからなかったためです。そのため、元の資料に戻らなければ、どちらの数値も検証できませんでした。自分のツールをドッグフーディングすることで、すばやく信頼を得られます。作者の間違いを反証可能にするツールは、さらに大きな信頼を得られます。そして、そのほうが作るのは困難です。

3つのツール

ツール	入力	出力
audit_intent_spec	仕様書（spec_text または file_path）	25点満点のスコア、セクションごとの指摘、検出されたアンチパターン、上位3つの推奨事項
generate_intent_spec_scaffold	kind（blank / level-1-mvr / full-9-section）、任意のヒント	そのまま貼り付けられる YAML のひな形と次のステップ
assess_retrofit_level	既存のプロンプトまたは SKILL.md	波及範囲、複雑さ、自律性を考慮した、推奨する改修レベル（L1 / L2 / L3）

25項目の検証チェックリスト、5つの致命的なアンチパターン、4段階の自律性レベル、9セクションのテンプレートは、すべて正規の intent-engineering スキルに基づいています。MCP サーバーは薄いプロトコルアダプターであり、フォークではありません。

クイックスタート

Node 20+ と MCP 対応クライアント（Claude Desktop、Cursor など）が必要です。

設定項目を1つ追加するだけで、クローンは不要です。 ~/Library/Application Support/Claude/claude_desktop_config.json に次の内容を追加します。

{
  "mcpServers": {
    "intent-engineering": {
      "command": "npx",
      "args": ["-y", "@swins/intent-engineering-mcp"]
    }
  }
}

または、ソースから実行します。

git clone https://github.com/seanwinslow28/sw-mcp-intent-engineering.git
cd sw-mcp-intent-engineering
npm install
npm run build

次に、設定の command を node に設定し、args: ["<ABSOLUTE_PATH_TO_REPO>/build/index.js"] を指定します。

Claude Desktop を再起動します。Settings → Developer を開き、サーバーの状態が running と表示されることを確認します。

新しい会話では、ツールリストの intent-engineering の下に3つのツールが表示されます。

試してみる

サーバーに接続した後、Claude Desktop に次の内容を貼り付けます。

この仕様書に対して audit_intent_spec を実行してください：

## Objective
Make support tickets resolve faster.

## Outcomes
- Tickets close in <2h
- CSAT stays high

## Stop Rules
(none)

25点満点のスコア、検出されたアンチパターンの一覧（この仕様書では少なくとも3つ検出されます）、修正のための具体的な推奨事項が3つ返されます。入出力の契約全体は docs/v0-scope.md §4 に記載されています。

ドッグフーディングの結果と、それに伴う訂正

2026-08-29にファイル全体を再評価しました。正規の intent-engineering SKILL.md は、アンチパターンの検出なしで23/25です。 7つのセクションは合格、2つは警告、欠落はありません。これは32,356文字すべてを評価した結果であり、応答の coverage ブロックにその旨が示されています。

1回の呼び出しで再現できます。

audit_intent_spec({ file_path: "<path>/.claude/skills/intent-engineering/SKILL.md" })

このページには誤った数値が掲載され、その後、誤った訂正が掲載されました

上記の23/25は、このページで2026年5月に公開され、2026-08-28に撤回され、2026-08-29に復元された数値です。間違いは撤回のほうでした。その文の根拠となるすべての測定値を示します。これにより、信頼するのではなく、推論を検証できます。

評価対象	スコア	アンチパターン
5月時点のファイル（17,885文字）、全体	23/25	なし
5月時点のファイル、先頭10,000文字	17/25	1
現在のファイル（32,356文字）、全体	23/25	なし
現在のファイル、先頭10,000文字	14/25	2
ファイル末尾を超える位置から始まる読み取り	当時は1/25、以降は0/25	2

元の評価が正しかった理由。 5月時点で、スキルの文字数は17,885文字でした。max_length は20,000文字に制限されているため、ファイル全体が1回の呼び出しに収まり、フェーズ3の「最初のチャンク」は文書全体でした。そのセッションの往復テストの表にある「1/25」の行は、末尾を超える位置から読み取りを開始し、実際の内容を部分的に評価したものではなく、0文字を評価したものです。（この「1/25」自体にも小さなバグがあり、今回の再訂正と同じ日に修正されました。条件付きのルーブリック項目の1つが「該当なし」を合格として扱っていたため、認識されない文書でも1点を獲得していました。現在は、何も認識されない文書のスコアは「0/25」です。）

スコアは一度も変わっていません。 全体を評価した場合、Gitの履歴にあるスキルのすべてのリビジョンで同じスコアになります。

リビジョン	文字数	ファイル全体のスコア	20,000文字の呼び出し1回に収まるか
ebf41b3d 2026-03-03	17,942	23/25、アンチパターン0件	はい
9c76e762 2026-05-04	17,885	23/25、アンチパターン0件	はい
d0117843 2026-06-10	17,900	23/25、アンチパターン0件	はい
c8f90d79 2026-07-05	32,356	23/25、アンチパターン0件	いいえ

スコアは5か月間、さらにファイルがほぼ倍の長さになったコミットを経ても安定しています。また、ファイルがまだ1回の呼び出しに収まっていた2026-06-17の作業セッションでも、独立して再確認されています。2026-07-05に変わったのは評価結果ではなく、測定可能性でした。ファイルが上限を超え、それ以降、1回の呼び出しだけでは公表済みのスコアを検証できなくなったのです。

それでも撤回された理由。 7月までにスキルは32,356文字に増え、20,000文字の上限を超えたため、1回の呼び出しでは全体を評価できなくなりました。2026-08-28の再測定では既定値の10,000文字を使い、14/25という結果を得ました。23/25と一致しなかったため、元のスコアはファイル全体ではなくチャンクを評価したものだと結論づけました。その誤りの説明自体は完全に正しかったのですが、誤っていたのは適用対象です。新しい方がチャンクでした。

2つの誤りは同じ原因によるものです。 4か月間、このツールはスコアが文書全体を対象としたものかどうかを判別できず、作成者にも判別できませんでした。5月の主張も8月の撤回も、出力のどこにもその事実が示されないまま公表されました。一方はたまたま正しく、もう一方は誤っていました。正確であるための方法として、これほど役に立たないものはありません。

これは仕様監査ツールなので、明確に述べておくべきことが2つあります。

• ツールは一度も間違っていません。読み取る側が、正反対の方向に2回間違えました。 "14/25" と "23/25" は同じ形式の文字列です。回答には、10,000文字の評価なのか32,356文字の評価なのかを区別する情報が何もなかったため、どちらの解釈も一見しただけでは反証できず、そのまま公表されました。
• 訂正も主張の1つであり、訂正対象と同じ来歴情報が必要です。 撤回は慎重に書かれ、自身のセッションの表を引用していましたが、それでも誤っていました。差し替えた数値が実際に何を評価したのかを確認していなかったからです。自分の誤りに気づくことはゴールではありません。分母を明記した測定によって自分の誤りに気づくことが重要です。

2026-08-29に修正。修正が必要になった理由もここにあります。 audit_intent_spec は既定で文書全体を評価するようになり、すべての回答に、評価モード、評価した文字数、利用可能な文字数、評価が完全かどうかを示す coverage ブロックが含まれるようになりました。部分評価を指定することは引き続き可能です。ただし、完全な評価と取り違えることはもうありません。 大規模な場合：同じサーバーで、私の Claude Code Superuser Pack に含まれるファーストパーティーのスキル全 118 件を評価したところ、解析エラーはゼロで、1 秒もかかりませんでした — いずれも 2026-08-28 に再計測済みです（94 ms、エラー 0 件。同じ 118 個のファイルに対して scripts/audit-superuser-pack.ts のロジックを実行）。出荷時の CSV examples/superuser-pack-retrofit-assessment.csv（2026-05）では、24% が L1-mvr（仕様に必要なのはインテントヘッダーのみ）、36% が L2-structured（Health Metrics と Decision Authority が必要）、40% が L3-full（9 セクションへの変換に値する自律ループ型、または影響範囲の大きいスキル）でした。現在の同じファイルの内訳は 20% / 38% / 42% です — 変化したのはコーパスであり、ツールではありません。assess_retrofit_level には、上記の危険性が記載されたことは一度もありません。常にファイル全体を読み込み、1 MiB を超えるものは明確に拒否していたため、この CSV の一括評価で部分読み込みが行われたことはありません。2026-08-29 時点で、audit_intent_spec はデフォルトで同じく文書全体を処理するようになっています。

制限事項

この監査は見出し構造について独自の見解を持っていますが、現在は正式な見出しに加え、保守的な別名見出しも認識します — ## Purpose / ## When to Use は Objective に、## Success Criteria / ## Definition of Done は Desired Outcomes に、## Completion / ## Exit Criteria は Stop Rules に対応し、以下同様です（全テーブルは src/intent/parser.ts にあります）。正式ではない見出しからセクションを認識した場合、監査は注記でそのことを示すため、スコアの根拠がわかりやすく保たれます。以前は、異なる見出し語彙を使うスキルのスコアが 1/25 になっていました。存在するセクションがひとつも認識されなかったためです。この誤検出は修正済みです。誠実に明示すべき境界が 2 つ残っています。真にインテントと同等ではない見出し（## How to Apply、## Instructions、## Usage などの手順を示す見出し）は、誤ったセクションに加点されないよう、意図的に対応付けていません。また、仕様に 9 つのインテントセクションが実際に欠けていれば、スコアは低いままです — マッパーが認識するのは同等のインテントであり、インテントを創作するわけではありません。

あらかじめ明示しておくべき、その他の v0 の境界：

• 読み取り専用です。 ツールはファイルを書き込みません。assess_retrofit_level は推奨を行いますが、レトロフィットは行いません。v0.2 の apply_retrofit は、明示的なユーザー確認の後にのみ実行されるものです。
• Stdio トランスポートのみです。 Streamable HTTP、SSE、リモートホスティングには対応していません。クライアントの隣でローカルに実行してください。
• prompts プリミティブと resources プリミティブはありません。 ツールは 3 つだけです。インターフェースが安定する前に増やすのは時期尚早です。

プロジェクト構成

sw-mcp-intent-engineering/
├── src/
│   ├── index.ts                    # MCP server boot + tool registration
│   └── intent/
│       ├── audit.ts                # audit_intent_spec logic
│       ├── scaffold.ts             # generate_intent_spec_scaffold logic
│       ├── retrofit.ts             # assess_retrofit_level logic
│       ├── checklist.ts            # 25-item validation checklist
│       ├── anti-patterns.ts        # 5 fatal anti-pattern detectors
│       ├── parser.ts               # YAML frontmatter + markdown heading parser
│       └── templates/              # YAML scaffolds (blank / level-1-mvr / full-9-section)
├── docs/
│   ├── v0-scope.md                 # binding scope-lock for v0
│   ├── EXPLANATION.md              # 4Q comprehension artifact (why MCP, what would break, what I learned)
│   └── claude-code-responses-and-tests/   # archived phase-verification outputs
├── package.json
├── tsconfig.json
├── server.json                     # registry metadata
├── CHANGELOG.md
├── README.md
└── LICENSE

src/index.ts は薄いプロトコルアダプターです。すべてのツールロジックは src/intent/* にあります。

ビルドの方針

• SDK は @modelcontextprotocol/[email protected] に固定しています（安定版の v1.x 系列であり、v2 のプレアルファ版ではありません）
• すべてのログは console.error に出力します。prepublishOnly の grep ガードにより、src/ に console.log があるとビルドに失敗します
• ツールの実装では、スキルと同じ内容を反映するローカルモジュールから、検証チェックリスト、アンチパターンの定義、テンプレート文字列をインポートします。スキルの内容を言い換えたり、独自に作り直したりはしません
• スコープの変更には、コードを書く前に CHANGELOG.md で明示的な承認が必要です

さらに読む

• docs/EXPLANATION.md — 4Q の理解用資料（これは何か、このアプローチを選ぶ理由、何が壊れるか、何を学んだか）
• docs/v0-scope.md — 拘束力のある v0 スコープロックとリリースゲート
• seanwinslow.com/transactions/intent-engineering-mcp — Loom デモを含む詳細な解説記事

ライセンス

MIT。詳細は LICENSE を参照してください。