WORK

docaudit

macOS上で動くドキュメント監査CLIで、Claude Codeのプラグインとしても使えます。GitリポジトリのMarkdownドキュメントをコード・設定と照合し、判定結果を最終行のJSONで返し、不一致のサマリーを含むMarkdownレポートをリポジトリに書き出します。監査対象のドキュメントは編集せず、結果をレポートします。

利用者と課題

FFmpegコマンドジェネレーターの制作時から、実装や設計書を作った後に、実装とドキュメントの食い違いをチェックするプロンプトを何度も入力していました。毎回入力するのが面倒でした。Nextcloudのプロジェクトなど、規模が大きくなると1回のプロンプトでは全部を整備しきれず、自動や半自動である程度進めるツールを作りたいと思いました。

機能

  • Claude Codeで/docaudit:audit --fullを実行すると、選んだプロファイルの全対象ドキュメントを監査し、結果がCONSISTENTのときなどにプロファイルごとのアンカーを作成し、以後は/docaudit:auditでアンカーからの変更に影響されるドキュメントを監査します。
  • プロファイルは--profile focused|standard|extendedで指定でき、focusedはドキュメントの照合、standardはプロジェクトチェックの追加、extendedはセキュリティレビューや矛盾の指摘とその再検証などの追加に対応し、指定しないときは通常standardで、変更の規模などの条件を満たしfocusedのアンカーがあるときはfocusedが自動選択されます。
  • 判定バックエンドは--backend codex|agy|claudeでCodex・agy・Claude Codeから選べ、Claude Codeのスキルでは複数のバックエンドが利用可能な場合に選択肢を表示し、選択のないコマンド実行ではCodex、agy、Claude Codeの順で最初に利用可能なものを使います。
  • Claude Codeの外ではpython3 ~/.claude/skills/docaudit/skills/audit/engine audit --full --profile standard --repo-root /path/to/repoの形で、監査対象のリポジトリとプロファイルを指定できます。
  • 監査の前に対象を確かめるときは、同じエンジンにscope --repo-root /path/to/repoを渡すと、変更ファイルのchanged、監査対象のimpacted、対象になった理由のprovenanceを含むJSONオブジェクトを返し、AIを呼び出さず、リポジトリ・状態・レポートのファイルも書き込みません。
  • 実行結果は最終行のJSONにnextAction・outcomeと、該当する場合のreason・reportPathを返し、結果の区分はCONSISTENT・NEEDS_FIX・undecided・REFUSEDです。
  • CONSISTENTまたはNEEDS_FIXで終了した監査は、確認したドキュメント、ドキュメントごとの判定と不一致のサマリー、プロジェクトチェックなどの指摘をMarkdownレポートにまとめます。
  • standardとextendedでは、必須front matter、ローカルリンク、バッククォート内のパス、ほかのドキュメントやインデックスからリンクされていないドキュメントをチェックし、独自のチェックコマンドも追加できます。
  • Codexのドキュメント照合は1回900秒、1ドキュメントにつき最大3回、同時実行は最大4件で、利用できないモデルへの呼び出しが失敗した場合は判定を確定せず、undecided backend-failedを返します。

使用技術

  • 監査エンジンはPythonで、標準ライブラリを使用し、変更の取得にはGitを使います。
  • Claude Codeとの連携にはプラグイン・スキル・エージェント・JavaScriptのWorkflowを使います。
  • 外部AIは、Codex CLI経由のGPT-6.1-Sol Medium、agy CLI経由のgemini-3.8-flash-medium、Claude Code経由のClaude Sonnet 5.5 Highを使用します。
  • macOSの書き込みガードで監査が書き込める場所を制限し、独自のチェックコマンドはsandbox-execで一時ディレクトリの外への書き込みを制限して実行します。
  • GitHubで配布し、リリースタグのファイルを配置する方法と、Claude Codeのプラグインマーケットプレイスからインストールする方法を用意しています。

制作期間

前身のdoc-audit-harnessから数えて、2026年6月4日〜11月7日です。

工夫した点

前身のdoc-audit-harnessが複雑になり、作り直しました。前身では1回の監査にかかる時間とAIのトークン使用量が多かったため、機械で判定できる部分を機械判定にし、残りをAIが判定する方針にしました。相対リンクのリンク先が存在するかを機械判定でチェックしたドキュメントでは、同じチェックをAIに重ねて依頼せず、AIにはコードや設定との意味上の不一致を照合させるようにしています。この場合、相対リンクのリンク先の存在は機械判定が、ドキュメントに記載された値・数量・原因・手順とリポジトリとの照合はAIが受け持つように分担しています。正確さとスピードを保ちながら、自分以外のユーザーがどう使えるかを意識しています。Codexのデフォルトモデルは2026年9月にGPT-5.6-Terra MediumからGPT-6-Luna xhighへ変更し、10月にGPT-6.1-Sol Mediumへ変更しました。モデルを測り直し、GPT-6.1-Sol Mediumに落ち着きました。監査の履歴が残るので、AIに任せて開発するときに、その履歴をたどることもできます。今後も、できる限り機械で判定してから残りをAIが判定する形で、もっと軽く早く監査できるようにしていきたいと考えています。

リンク