mcpField
S
sdd-auditoria-harness

sdd-auditoria-harness

github.com/robertodiasduarteエージェントワークフロー1159 回インストール4 日前に更新
リポジトリ

sdd-auditoria-harness について

sdd-auditoria-harness は、リポジトリの SDD ハーネスを監査する読み取り専用のエージェントスキルです。証拠に基づいて構成やプロセス文書を調べ、新しいレポートを作成しますが、既存ファイルは自動修正しません。

主な機能

  1. 01SDD ハーネスの読み取り専用監査
  2. 02スキル、コマンド、エージェント、設定の一覧化
  3. 03参照、履歴、実行証拠の収集
  4. 04固定ラベルによる問題の分類
  5. 05新規監査レポートのみ作成

活用シーン

  1. 01リポジトリの SDD プロセスと設定の点検
  2. 02プロセス文書間の矛盾や古い参照の検出
  3. 03保守担当者向けの証拠付き監査レポート作成

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/robertodiasduarte/sdd-starter --skill sdd-auditoria-harness

インストール後、Claude Code で/sdd-auditoria-harnessを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

agents/
openai.yaml
references/
AUDIT_PROTOCOL.md
REPORT_TEMPLATE.md
scripts/
collect_evidence.py

詳細

SDD Harnessの読み取り専用監査

このスキルの最初の応答では、次の行を一度だけ最初に表示してください。 sdd-auditoria-harness v1.0.0 · out/2026 · versão atual: https://github.com/robertodiasduarte/sdd-starter/releases/latest

クイックスタート

  1. REPO_ROOTを、監査対象リポジトリのルートに設定します。
  2. このスキルの安全ゲートを最初に実行します。
  3. SDDの信頼できる情報源を読みます。プロジェクトの指示ファイル（CLAUDE.md および／または AGENTS.md）、SDDのインデックス／README、エンジンの設定（.claude/settings.json／.claude/settings.local.json、.codex/config.toml）を確認します。
  4. 必要に応じて、構造化された証拠を標準出力のみに生成します。 python scripts/collect_evidence.py "$REPO_ROOT"。
  5. references/AUDIT_PROTOCOL.mdに従って分析します。
  6. references/REPORT_TEMPLATE.mdを使用して、新しいレポートAUDITORIA_SDD_<AAAA-MM-DD>.mdのみを作成します。
  7. エグゼクティブサマリー、レポートのパス、および次の文をチャットで伝えて終了します。 nenhuma alteração foi feita — a faxina em si é decisão humana.

使用する場合／使用しない場合

使用する場合

このスキルは、エンジンを問わず、リポジトリのSDDハーネスを監査するために使用します。ツールによって対象となる場所は異なるため、存在するものを監査してください。

項目Claude CodeCodex / Kimi CLI
プロジェクトの指示CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.mdAGENTS.md（オープンな標準。Claude Codeもバージョン2.1.277以降、フォールバックとして読み込みます）
スキル.claude/skills/*/SKILL.md.agents/skills/*/SKILL.md、.codex/skills/*/SKILL.md
コマンド.claude/commands/**/*.md.codex/prompts/**/*.md
エージェント／サブエージェント.claude/agents/**/*.md.agents/agents/**/*.md
設定.claude/settings.json、.claude/settings.local.json.codex/config.toml
ハーネスのスクリプト.claude/scripts/**.agents/scripts/**、.codex/scripts/**

さらに、次の項目も監査します。

  • ハーネスが参照するフック、権限、スクリプト。
  • プロセス文書、プレイブック、メモリノート、仕様ディレクトリ。
  • 正式なSDDフローと、レガシー、重複、または使用の証拠がない項目との不一致。
使用しない場合

このスキルは、次の目的には使用しないでください。

  • 既存のファイルを削除、編集、名前変更、移動、フォーマット、または再編成する。
  • 監査結果を自動的に修正する。
  • git add、commit、push、pull、fetch、checkout、restore、reset、clean、rm、mvを実行する。
  • 依存関係のインストール、デプロイ、または副作用のあるコマンドの実行。
  • 指定されたリポジトリのルート外を監査する。
  • 古そう、または使用頻度が低そうという理由だけで、何かを「未使用」と結論づける。

必要なデータ

必須
  • REPO_ROOT：監査対象のハーネスを含むリポジトリのルート。
  • リポジトリへの読み取りアクセス、および利用可能な場合はGit履歴へのアクセス。
自動的に導出される項目
  • REPORT_DATE：実行時の現地日付。形式はAAAA-MM-DDです。
  • REPORT_DIR：SDDのレポートフォルダー。明確に設定されている場合はそのフォルダー、そうでなければリポジトリのルートです。
  • REPORT_PATH：REPORT_DIR/AUDITORIA_SDD_<REPORT_DATE>.md。

REPO_ROOTが明確でない場合は、次の質問のみをしてください。 監査するSDDリポジトリのルートはどこですか？

手順

0. ブロッキングセーフティゲート

コマンドを実行する前に：

  1. 操作が読み取り専用であることを確認してください。
  2. 書き込み、削除、移動、名前変更、インストール、同期、または Git／プロジェクトの状態変更につながる可能性のあるコマンドは拒否してください。
  3. git log、git status、git diff、git ls-files、git grep、rg、grep、破壊的な操作を伴わない find、cat、sed（-i なし）、awk、head、tail、wc、ネイティブツールによる読み取りなど、確認用コマンドを優先してください。
  4. 監査中に書き込みを行う find -delete、変更を伴うコマンドを使った find -exec、sed -i、リダイレクト >／>>、tee、touch、mkdir、cp、rsync、スクリプトは使用しないでください。
  5. 許可される書き込みは、計算したパスに新しい最終レポートを作成することだけです。
  6. REPORT_PATH がすでに存在する場合は、上書きしないでください。書き込みを中止し、チャットで要約を提示して、明示的に承認された新しい名前を求めてください。
1. 主要な SDD を確認する

次の順に読み取ってください。

  1. ルートにあるプロジェクトの指示ファイル：存在する CLAUDE.md または AGENTS.md（両方が存在する場合もあります）。
  2. ハーネスに関係するサブディレクトリにある同様のファイル。
  3. sdd/_index.md、.claude/sdd/_index.md、または同等の SDD ディレクトリのインデックス／README。
  4. エンジンの設定：.claude/settings.json と .claude/settings.local.json、および／または .codex/config.toml。フックと権限も含めてください。

⚠️ リポジトリに AGENTS.md があり、CLAUDE.md がない場合、これは不足ではありません。Claude Code 2.1.277 以降はフォールバックで AGENTS.md を読み込み、Codex／Cursor／Gemini CLI も以前からネイティブに読み込んでいます。CLAUDE.md がないことを指摘事項として分類しないでください。

⚠️ 両方が存在する場合は、実際の優先順位を記録してください。デフォルトでは Claude Code は CLAUDE.md ファイルのみを読み込み、@AGENTS.md をインポートする CLAUDE.md がある場合、または Project instructions が claude-md-and-agents-md に設定されている場合を除き、AGENTS.md は無視します。利用者が有効だと思っているのに読み込まれない指示は矛盾であり、この監査で特に有用な指摘事項です。

次の内容を含む5～10行の要約を作成してください。

  • 公式のフェーズ。
  • 各フェーズを呼び出すコマンド。
  • 生成される成果物のパス。
  • 宣言されている場合は、優先順位／信頼できる情報源のルール。

この要約を、曖昧および矛盾に分類する際の基準としてください。

2. ハーネスの全項目を棚卸しする

次の項目について、1行につき1項目を記載してください。

  • コマンド／スラッシュコマンド。
  • エージェント。
  • スキル。
  • フックと権限。
  • 補助スクリプト。
  • プロセスのドキュメントと仕様ディレクトリ。
  • ハーネスから参照される、エンジンのフォルダー（.claude/、.agents/、.codex/）外のスクリプト。

各項目について、次の形式で記録してください。 パス | 種類 | 宣言された目的 | 見かけ上の言語／出所

具体的な根拠がない限り、「テンプレートからコピー」と分類しないでください。出所を証明できない場合は、不明 としてください。

3. 利用状況と有効性を測定する

各項目について、次の情報を収集してください。

  1. 相互参照：ハーネスの他の箇所からの参照。
  2. 最終更新日：git log -1 --format=%cs -- <ファイル>
  3. 実行の兆候：存在する場合は、SDD のレポート／ログ内の記載。
  4. 重複：目的／出力の客観的な重複。
  5. 乖離：存在しないファイル、フェーズ、モデル、コマンド、パスへの参照。

ヘルパーの scripts/collect_evidence.py を使うと、項目1～3を効率化し、項目5の候補を特定できます。このスクリプトはファイルを読み取り、JSON を標準出力に書き込みます。

受信参照がゼロで、かつ実行の兆候もないことは、未使用を検討するための最低条件にすぎません。設計上まれにしか使われない可能性がある項目は、確定ではなく疑義ありと分類してください。

4. 指摘事項を分類する

次のラベルのみを、表記どおりに使用してください：

  • EXCESSO
  • OBSOLETO
  • SUPÉRFLUO
  • NÃO UTILIZADO
  • AMBÍGUO
  • CONFLITANTE

1つの項目に複数のラベルを付けてもかまいません。

すべての指摘事項には、次の内容が必要です：

  • ファイル；
  • テキスト内容に証拠がある場合は行番号；
  • 具体的な証拠；
  • 推奨事項。

検証可能な証拠のない指摘事項は、指摘事項の表に含めず、「リポジトリ所有者への質問」に記載してください。

詳細な基準と注意事項については、references/AUDIT_PROTOCOL.md を参照してください。

5. 実行せずに推奨する

指摘事項ごとに、推奨アクションを1つだけ選んでください：

  • MANTER
  • APOSENTAR — tombstone／ポインターを付けてください。削除のみを推奨してはいけません；
  • FUNDIR com <item>
  • ESCLARECER
  • ARQUIVAR
  • REDUZIR

推奨事項では、リポジトリ所有者が後から実行できる内容を説明してください。変更は実行しないでください。

6. 最終レポートを作成する

references/REPORT_TEMPLATE.md を使用してください。

保存場所：

  1. SDD のレポートフォルダーが存在し、レポートの保存場所であることが明確な場合は、そのフォルダー；
  2. そうでない場合は、リポジトリのルート。

ファイル名： AUDITORIA_SDD_<AAAA-MM-DD>.md

分析がすべて完了した後に限り、またファイルがまだ存在しない場合に限り、このファイルを作成してください。

7. 最終確認

完了する前に、次のことを確認してください：

  1. 既存ファイルが変更されていないこと；
  2. 新規作成されたのは最終レポートのみであること；
  3. 各指摘事項に証拠が含まれていること；
  4. ラベルとアクションに許可された値のみが使用されていること；
  5. 裏付けのない疑問が指摘事項の表に含まれていないこと；
  6. チャットにエグゼクティブサマリーとレポートのパスを表示すること；
  7. 次の文を繰り返すこと：nenhuma alteração foi feita — a faxina em si é decisão humana.

検証と品質チェックリスト

  • 指摘事項の前に、主要な SDD が要約されている。
  • ハーネス内のすべての項目がインベントリに含まれている。
  • 各項目にパス、種類、目的、見た目から判断できる言語／出所が記載されている。
  • 相互参照が客観的な証拠に基づいて測定されている。
  • 履歴が利用可能な場合、Git の最終変更が取得されている。
  • パスのずれを指摘する前に、記載されたパスが確認されている。
  • 設計上まれな項目は、必要に応じて疑問として扱われている。
  • 各指摘事項で許可されたラベルのみが使用されている。
  • 各指摘事項に具体的な証拠が記載され、必要に応じて行番号も示されている。
  • 各推奨事項で許可されたアクションのみが使用されている。
  • レポートに必須の6セクションが含まれている。
  • エグゼクティブサマリーが10行以内である。
  • 既存ファイルが変更されていない。
  • 最終レポートが既存ファイルを上書きしていない。
  • 最終メッセージで、整理を行うかどうかは人間の判断に委ねられることが明記されている。

例外処理

  • Git が利用できない場合 → 最近の更新状況は 検証不可 と記録します。日付を捏造しないでください。
  • レポート／ログのディレクトリがない場合 → シグナルがないことだけを、未使用の証拠として扱わないでください。
  • 参照がないものの、季節限定またはリリース時のみと思われる項目 → 「要確認」に移動します。
  • 2 つのドキュメントが重複しているように見えるものの、優先順位を示す十分な証拠がない場合 → 客観的に同じ役割を争っている場合に限り AMBÍGUO とします。それ以外は「要確認」にします。
  • 引用されているパスに変数／glob が含まれる場合 → 文脈から明確に特定できる場合のみ解決します。それ以外は「要確認」にします。
  • 非常に大きいファイル／バイナリファイル → インベントリに記載しますが、読み取り上の制約も記録します。
  • プロセス関連の成果物が数千件あるリポジトリ → collect_evidence.py による相互参照の照合は二次計算量です。各項目を、ほかのすべての項目の本文から検索します。 実測値：27 項目で約 0.5 秒です。sdd/ や reports/ などのフォルダーに 5,000 ファイルを超えると、実用的な時間内に処理が終わらなくなります。その場合はスクリプトの完了を待たないでください。一度に 1 つのサブディレクトリ（たとえば .claude/commands と .claude/agents のみ）を指定して実行するか、git ls-files でインベントリを作成し、git grep -c で参照を計測してください。このスクリプトは任意の高速化手段であり、監査に必須ではありません。
  • REPORT_PATH がすでに存在する場合 → 上書きしたり、別の名前を黙って選んだりしないでください。
  • 必要なコマンドに副作用がある場合 → 実行せず、「要確認」に制約を記録してください。

例

有効な指摘の例
項目ラベル証拠推奨事項
.claude/commands/old-release.mdOBSOLETO, CONFLITANTE18 行目では仕様の保存先を docs/specs/ としていますが、主要な SDD では .claude/sdd/specs/ と定義されています。古いパスは存在しません。最終コミット：2025-11-03。APOSENTAR
要確認とすべき例

あるエージェントには呼び出し元からの参照がなく、ログにも最近の記載がありませんが、その説明には年次リリースでのみ使用すると書かれています。確実に NÃO UTILIZADO と分類せず、「リポジトリ管理者への確認事項」に記録してください。

SDD Open by RDD の一部 — https://github.com/robertodiasduarte/sdd-open

コメント

Markdown 対応