はじめに — 全テスト通過、ビルド成功、でもドキュメントは嘘をついていた
199テスト全パス。ビルド成功。npm audit の本番依存にクリティカルな脆弱性ゼロ。npm pack --dry-run で公開ファイルも想定通り。
MCP Server v0.5.0のnpm公開準備は完了した——はずでした。
ところが、公開前チェックリスト（mcp-npm-publish-guide.md）に従ってCHANGELOGとREADMEの整合性チェックを実行したところ、3つの数値不整合が見つかりました。コードは正しいのに、ドキュメントが間違っている。テストもCIも検出しない種類の品質問題です。
公開前チェックリストはドキュメントの品質も担保する: コードのビルド・テスト合格だけでなく、CHANGELOG・README・公開ガイドの整合性チェックが 3 つの数値不整合を発見した。「動くコード」と「正確なドキュメント」は別の品質軸
2月22日の開発日記にこう書きました。この記事では、MCP Server開発を通じて繰り返し直面した「ドキュメントの不正確さ」の問題と、それを体系的に検出するチェックリスト駆動の品質管理について書きます。
v0.5.0で発見された3つの不整合 — 数字の嘘
v0.5.0はPhase 3.5の成果物です。Tier 1に4つの新規検査ツール（キャッシュヘッダー、構造化データ完全性、リダイレクトチェーン、画像最適化）を追加し、Tier 2のチェックリストも大幅に拡張しました。MCP Serverの全体設計については「MCP Server開発記」を参照してください。
コード実装とテスト追加が完了し、npm公開手順ガイドに従ってCHANGELOG/READMEの記述をレビューしたとき、3つの不整合が見つかりました。
不整合1: 「3 new items」は実は4つだった
CHANGELOGに「Web Launch Audit: 3 new items added」と記載されていましたが、実際に追加されたチェック項目を数えると4つでした。欠落していたのは schema completeness（構造化データの完全性チェック）です。
この不整合の根本原因は、CHANGELOGを書いた時点ではまだ実装途中で、最後に追加した項目が反映されなかったこと。コードの checklist-data.ts を精査すると、確かに4項目が定義されていました。
不整合2: 「20 auto + 1 manual」の合計が合わない
同じWeb Launch Auditについて、READMEに「20 auto + 1 manual checks」と記載されていましたが、上述の schema completeness を加えると正しくは「21 auto + 1 manual checks」。不整合1の連鎖です。1つの数え間違いが、下流の複数箇所に波及していました。
不整合3: 「chains 11 tools」は重複カウントだった
Freelance Delivery Auditについて、「chains 11 tools」と記載されていました。しかし実装コードで確認すると、ワークフロー内で使用されているユニークなツール数は8つでした。
Freelance Delivery の「chains 11 tools」問題: CHANGELOG/README に「chains 11 tools」と記載されていたが、実際にチェックリストで使用されているユニークツール数は8つだった。これは Phase 2.7 で追加された際にチェックリスト内の重複ツール参照をカウントしてしまったのが原因
この不整合は、ワークフローが同じTier 1ツールを複数のチェック項目から参照している設計に起因します。たとえば check_ogp は、OGPタグの検証とファビコンの存在確認の両方で呼び出されます。ツールの参照回数とユニークツール数は異なりますが、ドキュメントでは区別されていませんでした。
なぜテストもCIもこれを検出しないのか
3つの不整合に共通するのは、「コードは正しく動いている」という点です。
テストは checklist-data.ts にschema completenessが定義されていることを確認します。CIはビルドが通ることを確認します。しかし、CHANGELOGに書かれた「3 new items」という数字が正しいかどうかは、誰もチェックしません。
ドキュメントの数字は、テストの対象外です。「コードの品質」と「ドキュメントの品質」は、まったく別の品質軸として管理する必要があります。
型チェック、Lint、テスト、CI——これらはすべて「コードの品質」を担保する仕組みです。しかし「ドキュメントの品質」を担保する仕組みは、自分で作らなければ存在しません。
チェックリスト駆動の品質管理 — 3層の防御
MCP Server開発では、3つのチェックリストが異なるレイヤーの品質を担保しています。
第1層: mcp-dev-checklist.md（開発チェックリスト）
セキュリティ（SSRF対策、入力バリデーション）、ライセンス（npm supply chain）、品質（テスト、型安全性）、運用（タイムアウト、レート制限）をカバーする開発レビュー用チェックリストです。実装完了後に毎回レビューを実施します。
第2層: tools-dev-guidelines.md（ツール開発ガイドライン）
API routeのセキュリティとコスト管理に特化したガイドラインです。MCP ServerのTier 1ツールはAPI route経由で動作するため、このチェックリストも並行して適用します。
第3層: mcp-npm-publish-guide.md（公開前チェックリスト）
npmに公開する直前の最終チェック。バージョン番号、CHANGELOG/READMEの整合性、テスト結果、ビルド成果物、npm auditを確認します。今回の3つの不整合を発見したのは、この第3層です。
PM-AI 対話: チェックリストの守備範囲
ZeronovaZeronovaPhase 2.7の教訓 — コードは合格、ドキュメントに5件の不適合
v0.5.0が初めての経験ではありません。Phase 2.7（v0.3.0）でも同じパターンが発生していました。
mcp-dev-checklist.md 駆動の品質保証が効く: Phase 2.7 の実装完了後にチェックリスト準拠レビューを実施したところ、コード自体は全項目適合だったが、ドキュメント（CHANGELOG/README/checklist 自体）に5件の不適合を発見
2月18日の開発日記にはこう書いてあります。アクセシビリティ検証とセキュリティヘッダーチェックを追加したPhase 2.7では、コードは全チェック項目をパスしました。問題があったのはCHANGELOG、README、そしてチェックリスト文書自体でした。
Phase 3（v0.4.0）でも、チェックリストレビューで2件の不適合を発見しています。Zodスキーマの z.enum() 定義がチェックリストのツール一覧と整合していない問題と、タイムアウト処理の安全性に関する問題でした。こちらはコード側の問題でしたが、「チェックリストが問題を発見した」という点では同じ構造です。
毎フェーズ、チェックリストレビューが何かしらの問題を見つけています。見つからなかったフェーズはゼロです。
ドキュメント横断の不整合 — 「数値が複数箇所に出現する」問題
ドキュメントの不整合は、npm公開に限った問題ではありません。
2月19日に実施したドキュメント横断の整合性チェックでは、5件の不整合を修正しました。
- サイト構成ツリーのPhase番号が他の箇所と不一致（19.6 vs 19.7）
- MCP Serverのツール数が文書間で矛盾（18 vs 実際は16）
- Journal記事数が本文と進捗テーブルで不一致（55本 vs 67本）
- ブログ合計記事数が古い数字のまま（118本 vs 125本）
数値が複数箇所に出現するドキュメントは不整合リスクが高い: ツール数・記事数・Phase番号など、同じ情報が複数ファイルに散在している場合、更新漏れが必ず発生する
コードの世界では「Single Source of Truth」（唯一の原本）が基本原則です。プロダクトデータは products.ts で一元管理し、ツールデータは tools.ts で一元管理しています。しかしMarkdownドキュメント間では、同じ数値が複数箇所にハードコードされます。ある場所を更新しても、別の場所に同じ数字が残っていることに気づかない。
これはドキュメントの構造的な弱点です。
コードとドキュメントの「品質の非対称性」
ここまでの経験を振り返ると、コードとドキュメントの品質管理には根本的な非対称性があることがわかります。
コードには自動検証がある。型チェック、Lint、テスト、CI。書いた瞬間にフィードバックが返ってきます。MCP Serverの199テストは、実装の正しさを継続的に保証します。
ドキュメントには自動検証がない。CHANGELOGに「3 new items」と書いても、誰もそれが正しいか検証しません。READMEの「chains 11 tools」が「chains 8 tools」であるべきことは、人間が目で確認するまで誰にもわかりません。
この非対称性が、「コードの品質は高いのにドキュメントの品質は低い」という状況を生み出します。
もう1つの発見 — ドキュメントの嘘がコードのバグを暴く
v0.5.0の公開準備中に、ドキュメントの不整合を追いかけていく過程で、コード側のバグも1つ発見しました。
Web Launch Auditの新チェック項目として wl-schema-completeness（構造化データの完全性チェック）を追加したのですが、この項目が checklist-data.ts から欠落していました。ドキュメントに「schema completeness」が含まれていないのはドキュメントの問題だと思って調べたところ、コード側にもこの項目の定義が存在しなかったのです。
ドキュメントの不整合を突き合わせる作業が、コードのバグ発見につながる。これは予想していなかった副産物でした。
npm audit警告の判断 — 「影響なし」を記録する
v0.5.0の公開準備では、npm audit で hono@4.11.9 にlow severityのtiming comparison脆弱性が報告されました。これは @modelcontextprotocol/sdk の間接依存です。
対処方針は「影響なし」です。MCP Serverは hono の basicAuth / bearerAuth を使っていないため、timing comparison攻撃の対象になりません。
重要なのは、この「影響なし」の判断根拠を公開前チェックリストに明記したことです。次回の公開時に同じ警告が出ても、「前回は影響なしと判断した。理由はこれ」と即座に確認できます。脆弱性警告は「修正する」か「影響なしの理由を残す」のどちらか。放置は最悪の選択です。
SEO監査の自動化でも書きましたが、チェックリストの価値は「何をチェックしたか」だけでなく「なぜその判断をしたか」を残せることにもあります。
チェックリストが定着するまでの変遷
MCP Server開発における3層のチェックリストは、最初から設計されていたわけではありません。
Phase 1（v0.1.0）の時点では mcp-dev-checklist.md だけがありました。npm公開は「とりあえず npm publish を実行してみる」からスタートし、node_modulesを含めてしまう失敗を経て、mcp-npm-publish-guide.md が生まれました。
tools-dev-guidelines.md はもともとWebアプリ用のガイドラインでしたが、MCP ServerのTier 1ツールがAPI route経由で動作するため、Phase 3.5（v0.5.0）で新規API route追加時に適用範囲を拡張しました。
各チェックリストは「問題が起きた → チェック項目を追加」という帰納的なプロセスで育っています。最初から完璧なチェックリストを作ることはできません。失敗のたびに1行追加していくことで、プロジェクト固有の品質知識がドキュメントに蓄積されていきます。
学んだこと — ドキュメントの品質を担保する3つの原則
MCP Serverの6回のリリース（v0.1.0 ~ v0.5.0）を通じて、ドキュメント品質に関する3つの原則が見えてきました。
原則1: コードの検証とドキュメントの検証を分離する
テストとCIはコードだけを見ます。ドキュメントの検証には、人間による「突合」作業が必要です。この2つを同じタイミングで実行しようとすると、どちらかが雑になります。タイミングを分け、それぞれに専用のチェックリストを割り当てるのが効果的です。
原則2: 数値はユニークカウントで統一する
「chains 11 tools」の不整合は、ユニークツール数と参照回数を混同した結果です。ドキュメントに数値を記載するとき、「何をカウントしているのか」を明確にする必要があります。ユーザーから見た「使うツールの種類」はユニーク数です。
原則3: 定期的な横断チェックを行う
同じ数値が複数ファイルに出現するMarkdownドキュメントでは、更新漏れが構造的に発生します。コードの世界のようにSingle Source of Truthを徹底することは難しいため、定期的な横断チェックが現実的な対策になります。
おわりに — チェックリストは「記憶の外部化」
チェックリスト駆動の品質管理は、いうなれば「過去の失敗の記憶を外部化すること」です。
Phase 2.7でドキュメントに5件の不適合が見つかったから、Phase 3では公開前にドキュメント整合性をチェックする項目を強化した。Phase 3.5でもやはり3件の不整合が見つかった。完璧にはならない。しかし、チェックリストなしでリリースしていたら、これらの不整合はユーザーに届いていたはずです。
npmパッケージは一度公開すると unpublish に制約があります。READMEの数値不整合は「小さな問題」に見えますが、ユーザーがREADMEの数値とツールの実際の挙動に差異を感じると、パッケージ全体の信頼性に影響します。
コードはテストで守る。ドキュメントはチェックリストで守る。品質の軸が違うなら、品質管理の仕組みも別に用意する。それが6回のリリースで得た最大の学びです。
Zeronova（ゼロノバ）
Product Manager / AI-Native Builder
Web/IT業界19年以上・20以上のWebサービスを担当したPdM。東証プライム上場企業の子会社代表として事業経営を経験。現在はAIを駆使して企画から実装まで完結させる個人開発を実践中。