Claude CodeでOfficeアドインを開発する手順 — manifest検証とサイドロード

ExcelやWord向けの自作アドインをClaude Codeで作るとき、コードの生成よりつまずきやすいのは、その周辺です。manifestが不正でアドインが読み込まれない、サイドロードしたのに後始末ができず次の起動が壊れる、といった種類の失敗が多く、ここは手順どおりに動かせば確実に進められる部分でもあります。この記事では、Office.jsのアドインをClaude Codeに開発させる際に、manifestの検証、サイドロード、デバッグ、単体テストをどう任せるかを、Microsoftの公式手順に沿って扱います。

任せやすいのは検証コマンドの実行と手順の再現

Claude Codeに向いているのは、判定基準がコマンドの終了コードで決まる作業です。manifestの検証と単体テストがこれに当たります。サイドロードもコマンド1本で起動できる経路があるので、手順を固定すれば再現できます。

一方、Officeのデスクトップアプリ上でアドインが実際にどう見えるか、リボンのボタンが出たか、は画面を見ないと分かりません。Claude Codeに「動いたはず」と言わせず、人が目で確かめる箇所を最初から切り分けておくと、手戻りが減ります。

最初に決める: 統合マニフェストか、アドイン専用マニフェストか

手順は、アドインがどちらのmanifestを使うかで分かれます。ここを決めずに「サイドロードして」と頼むと、別方式のコマンドが出てきて失敗します。

Microsoft 365の統合マニフェスト(unified manifest)を使うアドインは、すべてのプラットフォームにはインストールできません。対応状況は次の表のとおりです。

非対応の環境の利用者にも配るなら、統合マニフェスト版とアドイン専用マニフェスト版の2本を作って配ることになります。社内向けで利用環境がMicrosoft 365サブスクリプションのWindowsに限られるなら、統合マニフェストだけで足ります。

この判断は、プロジェクトを作る前に人が決めるのが安全です。決めた結果は、次の節のとおりCLAUDE.mdに書いておきます。

CLAUDE.mdに書いておく確認コマンドと禁止事項

Claude CodeはCLAUDE.mdを毎セッションの開始時に読みます。メモリのドキュメントでは、ビルドやテストのコマンド、コーディング規約、よく使うワークフローを書く場所とされ、1ファイルは200行以内が目安です。アドイン開発では、次の内容を入れておくとClaude Codeの動きが安定します。

# Office アドイン開発のルール
 
- 対象: Excel / Word。統合マニフェスト(manifest.json)を使う
- manifest を変更したら、必ず `npm run validate` を実行して結果を確認する
- サイドロードは `npm run start:desktop`(無ければ `npm run start`)で起動する
- サイドロードを起動したら、Office の画面で確認してほしい点を書き出して止まる。
  確認済みと人が返してから `npm run stop` で停止する
- セッションを終える前に、停止が済んでいるかを必ず確かめる。
  サーバーのウィンドウやOfficeを閉じるだけでは停止しない
- Office を起動した状態でサイドロードを始めない。先に閉じる
- Office.js のロジックは `npm test` が通るまで直す

起動後に「確認点を書き出して止まる」の1行が肝です。画面での確認をClaude Codeが代わりに済ませたことにしないよう、人に渡すことを明文化しておきます。

manifestの検証をhooksに載せる

manifestの編集は、検証を忘れやすい作業です。Claude Codeのhooksで、manifestを書き換えたら検証が走るようにしておくと、確認漏れがなくなります。

Yeoman generator for Office Add-ins(Yo Office)かMicrosoft 365 Agents Toolkitで作ったプロジェクトなら、プロジェクトのルートで npm run validate が使えます。これは統合マニフェスト、アドイン専用マニフェストのどちらにも使えます。このコマンドはMicrosoft 365とCopilotのストア検証も行いますが、localhostのURLのような開発用の情報は許容されます。本番公開を想定した厳格な検証は、次のコマンドです。

npm run validate
npm run validate -- -p

このコマンドがうまく動かないときは、npx office-addin-manifest validate -p MANIFEST_FILE を使います。MANIFEST_FILE にはmanifestのファイル名を入れます。Yo OfficeでもAgents Toolkitでも作っていないプロジェクトは、office-addin-manifest を npm install -g で入れ、manifestのあるフォルダーで office-addin-manifest validate MANIFEST_FILE を実行します。

これをhooksに組み込みます。hooksガイドの保護ファイルの例と同じ形で、スクリプトが標準入力のJSONから対象ファイルのパスを取り出します。次は、manifest以外のファイルを素通りさせるスクリプトの例です。

#!/bin/bash
# .claude/hooks/validate-manifest.sh
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
 
case "$(basename "$FILE_PATH")" in
  manifest.json|manifest*.xml) ;;
  *) exit 0 ;;
esac
 
if ! OUTPUT=$(npm run validate 2>&1); then
  echo "manifest の検証に失敗しました:" >&2
  echo "$OUTPUT" | tail -n 20 >&2
  exit 2
fi
exit 0

これを .claude/settings.json に登録します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/validate-manifest.sh"
          }
        ]
      }
    ]
  }
}

スクリプトには実行権限が要ります(chmod +x .claude/hooks/validate-manifest.sh)。終了コード2は、公式のhooksガイドでは「アクションを止め、理由を標準エラー出力に書く」ための値です。理由がどこに届くかはイベントによって異なるため、PostToolUseでの挙動はhooksのリファレンスで確認してから使ってください。うまく届かない場合でも、CLAUDE.mdの「manifestを変えたら検証する」という指示が二重の保険になります。

サイドロードの起動と、後始末まで含めた手順

サイドロードは、開発中のアドインを配布用カタログに載せずにインストールして試す方法です。統合マニフェストのアドインのサイドロードは、使うツールとプロジェクトの作り方で手順が分かれます。Claude Codeに頼むときは、プロジェクトに合った1つをCLAUDE.mdに書き、他の経路を混ぜないことが大事です。

どの経路でも、起動する前にOfficeのデスクトップアプリを閉じておきます。一度の起動に数分かかることがあります。また、Officeのバージョンによってはアドインが完全には有効にならず、リボンにボタンが出ないことがあります。そのときはホームタブの「アドイン」ボタンから、一覧のアドインを選ぶと有効になります。

停止を飛ばすと次の起動で壊れる

停止については、手順書が繰り返し念を押しています。サーバーのウィンドウを閉じても、サーバーが確実には止まりません。Officeのアプリを閉じても、Officeがアドインの登録を解除するとは限りません。起動に使った経路と対になる停止コマンドを、必ず実行します。

Claude Codeに任せるなら、ここをCLAUDE.mdの禁止事項と終了手順にしておくのが効きます。順序は一意にしておきます。サイドロードを起動したら確認してほしい点を書き出して止まり、人が確認を終えたと返したら停止コマンドを実行します。セッションを終える前に停止が済んでいるかを必ず確かめる、と書いておけば、停止の抜けを防げます。

Agents Toolkit CLIで入れた場合は、atk install が返すtitle IDを覚えておく必要があります。このIDは、Windowsではレジストリの HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Wef\Developer\OutlookSideloadManifestPath\TitleId に記録されます。キー名にOutlookとありますが、公式の説明では、Agents Toolkit CLIで入れたすべてのアドインに当てはまります。記録されるのは最後に入れた1本だけです。先に入れた物を消す前に別の物を入れると、前のtitle IDの記録が失われます。そのため、公式はプロジェクトのルートに TitleID.txt として控えておくことを勧めています。title IDを控える作業は、Claude Codeに「起動結果のtitle IDを TitleID.txt に書く」と指示しておけば任せられます。

また、atk uninstall は --interactive false が必須です。manifestのIDを使う方式はAPIのバグで現状動かず、title IDを使う上記のコマンドだけが使えます。

Web版とMacのサイドロード

Web版のOfficeでは、アドイン専用マニフェストを使うYo Officeプロジェクトなら、新規ドキュメントの共有リンクを取って次のコマンドを実行します。

npm run start -- web --document {url}

{url} はOffice on the webかOneDriveで作ったドキュメントの共有リンクです。Macで開発する場合は、{url} を単一引用符で囲みます(Windowsでは囲みません)。初回は開発者モードを有効にするかを聞かれ、続けてmanifestを登録してよいかを聞かれるので、人が応答する必要があります。Web版のサイドロードでは、manifestがブラウザーのローカルストレージに保存されます。ブラウザーのキャッシュを消す、または別のブラウザーに切り替えると、サイドロードし直しになります。

Macのデスクトップ版は、統合マニフェストならExcel・PowerPoint・Wordのサイドロードに対応しますが、Outlookは対応しません。iPadは統合マニフェストでは対応しません。

デバッグは、サーバー側と画面側で担当を分ける

Officeアドインのデバッグは基本的に通常のWebアプリと同じです。ただし、環境ごとに使うツールが変わります。サーバー側のコードは、一般のWebアプリと同じ方法でデバッグできます。Office上で動くクライアント側のJavaScriptは、プラットフォームで分かれます。

Claude Codeが得意なのは、コードを読んで原因を推測し、修正案を出すところまでです。ブレークポイントを置いてステップ実行する操作は人の側になるので、役割を次のように分けておくと進めやすくなります。

• 人が開発者ツールで再現し、コンソールのエラー文言とスタックトレースを貼る
• Claude Codeがその出力とソースを突き合わせ、原因の候補と修正を出す
• 修正後は npm test と npm run validate をClaude Codeが走らせ、結果を人が画面で確かめる

読みやすいデバッグ用のOffice.jsが欲しいときは、office.debug.js が用意されています(https://officeapis.public.onecdn.static.microsoft/1/office.debug.js)。人間にとってステップ実行しやすい版ですが、公開時のHTMLには使わない前提の版なので、「デバッグ用URLに差し替えたら元に戻す」ことをCLAUDE.mdに書いておきます。

Visual StudioでのOfficeアドイン開発は、Visual Studio 2026から非推奨となり、将来のリリースで削除される予定です。Microsoft 365 Agents ToolkitかYo Officeでプロジェクトを作ることが勧められています。Claude Codeと組み合わせる前提でも、コマンドラインで完結するYo OfficeかAgents Toolkitの構成のほうが、CLAUDE.mdに書いた手順をそのまま再現できます。

Office.jsのロジックは単体テストで固める

Office JavaScript APIは、Officeのデスクトップアプリ内のWebViewで動く前提のため、開発機の単体テストのプロセスにはそのまま読み込めません。office-addin-mock でOfficeのオブジェクトを模擬する方法が、単体テストのドキュメントに載っています。JestとMochaのどちらでも使えます。

npm install office-addin-mock --save-dev

ドキュメントの例を基にすると、Excelのセル範囲のアドレスを返す関数のテストは次のような形になります。例示として示す形で、実際のプロジェクトでは関数名とモックの中身を自分のコードに合わせます。

const OfficeAddinMock = require("office-addin-mock");
 
const mockData = {
  workbook: {
    range: { address: "C2:G3" },
    getSelectedRange: function () {
      return this.range;
    },
  },
};
 
const contextMock = new OfficeAddinMock.OfficeMockObject(mockData);
 
test("getSelectedRangeAddress は選択範囲のアドレスを返す", async function () {
  expect(await getSelectedRangeAddress(contextMock)).toBe("C2:G3");
});

このモックには、Claude Codeにとって都合のよい性質があります。Office.jsのアプリケーション固有のAPIは、load を呼んでプロパティを読み込み、sync で反映してから値を読む決まりがあります。公式の説明では、モックは本番と同じように、load と sync を挟まずにプロパティを読むとテストが失敗します。エラーメッセージは本番に近い「Error, property not loaded」です。生成されたコードで load や sync の呼び忘れがあると、テストの時点で落ちるので、Claude Codeに「落ちたテストを直して」と繰り返し任せられます。

ただし、このテストが確かめるのは、模擬オブジェクトに対するロジックです。リボンの表示やタスクペインの描画は確認できません。

つまずきやすい点

ここまでで挙げた手順は、ExcelとWordを主な対象にしています。Outlookのアドインは、サイドロードの手順が別になっています。ドキュメントも、Outlookは専用の手順に誘導しています。

まとめ

Claude Codeにアドイン開発を任せるときは、結果をコマンドで判定できる作業を前面に出し、画面の確認は人に残します。manifestの検証はhooksに、サイドロードの起動と停止の対はCLAUDE.mdに、Office.jsのロジックの検証は office-addin-mock の単体テストに置くと、役割が明確になります。同じ発想で別の実行環境のプラグインを扱った例は、Chrome拡張のManifest V3やFigmaプラグインの開発手順にもあります。Excelのマクロ側をClaude Codeで書く方法はExcel VBAマクロの記事で扱っています。