tomevault-io audit-repo-skill
このskillは、repo内のAI利用ルール、repo固有skill、custom agent、review routing、検証手順を点検するためのauditワークフローである。目的は、共通skillとrepo固有skillの役割境界、配布性、安全条件、workflow接続を確認し、人間判断が不要な問題を同じ作業内で修正し、判断が必要な候補を整理することである。
使う場面
.codex/skillsや.codex/agentsを追加した後に整合を確認したい。- 共通skill更新後、repo内skillやAGENTS.mdが古くなっていないか見たい。
- GitHub公開前に、ローカルフルパス、secret、環境依存の記述を点検したい。
- reviewable gate、specialist reviewer、test_runner、verification手順のroutingを確認したい。
- repo内skillが増え、重複や責務の混線を整理したい。
- repo内運用資産を共通workflowへ寄せる前に、役割境界、配布性、安全条件を点検したい。
使わない場面
- auditではなく、repo内skillやagentの新規scaffoldが主目的の場合。
- 検証コマンドを実行する場合。
- review判定や専門reviewを行う場合。
- 新しいrepo内skillやagentをscaffoldする場合。その場合は該当するscaffold skillを使う。
- 削除、委譲、残置、分解、共通側不足の対応表を作る場合。その場合は
migrate-workflowを使う。
入力
確認対象はrepoの慣習に従う。一般には次を読む。
AGENTS.md.codex/config.toml.codex/skills/*/SKILL.md.codex/agents/*docs/contract/docs/work/の代表的なMarkdown成果物と、同じtask-idのstate file- CI workflow、project manifest、検証script
すべてを深掘りする必要はない。audit目的に関係するファイルを優先し、対象外は記録する。
Audit観点
役割境界
- 共通skillとrepo固有skillの責務が重複しすぎていないか。
test_runnerが修正やreview判定を担当していないか。- specialist reviewerが検証実行や実装修正を担当していないか。
- reviewable gateがrepo固有の深い設計判断を単独で承認していないか。
Workflow接続
wf-explore、wf-implement、wf-verify、wf-reviewへの戻り先が明確か。docs/work/<task-id>.mdとdocs/work/<task-id>.state.jsonの分担が、workflow間で矛盾していないか。idiotへ渡す人間判断が整理されているか。wf-review-triageやhandoffが必要な場面がないか。- 共通workflowへの移行対応表が必要な場合、
migrate-workflowへ戻すべきか。
配布性
- 個人ホームディレクトリ、一時ディレクトリ、個人checkout先などのローカルフルパスがskill本文や公開文書に固定されていないか。
- 別skillの資材を参照する時に、skill名と
assets/...、references/...、scripts/...など相対的なasset名で表しているか。 - repo固有コマンドが共通skill側へ混入していないか。
検証と権限
- 検証コマンドのsource of truthが明確か。
- taskごとの実行予定や結果をstate fileの
commandsに置き、長期的な検証コマンド一覧と混同していないか。 - snapshot、golden、fixture再生成、依存関係更新、migration、deployが暗黙実行されないか。
- sandbox権限、network、secret、外部service、GUI、localhost、artifact、timeoutの扱いが明記されているか。
- 実行していない検証を実行済み扱いしない出力形式になっているか。
セキュリティと公開前確認
- secrets、credential、本番DB接続情報、本番ログの生データが含まれていないか。
- auth、permission、tenant、PII、secret、ログ、外部入力を扱うskillに確認観点と人間判断の戻り先があるか。
- release、merge、本番操作、risk acceptanceをAIが承認する記述がないか。
手順
- audit目的と対象範囲を確認する。
- 対象ファイルを列挙し、読む優先度を決める。
- Audit観点ごとに finding を記録する。
- findingを severity、戻り先、
auto-fixable/needs-workflow/human-decisionで分類する。 auto-fixableは同じ作業内で修正し、必要なら関連するagents/openai.yamlや README も同期する。needs-workflowとhuman-decisionは、修正候補と戻り先を整理する。- 必要なら
docs/work/<task-id>-audit-repo-skill.mdにaudit結果を保存する。
自動修正できる条件
次をすべて満たすfindingは auto-fixable として扱う。
- 既存のAGENTS、skill本文、agent定義、README、install script、CI、manifestなどの証跡から修正内容が判断できる。
- 修正が誤記、古いpath、古いコマンド、明白な役割境界の同期漏れ、出力形式の欠落、禁止事項の記述漏れ、READMEや
agents/openai.yamlの説明同期に閉じる。 - repo固有の仕様、review方針、risk acceptance、security、privacy、release、本番操作の判断を含まない。
- 破壊的操作、削除、大きな移行、責務分解、共通workflowへの移行判断を含まない。
判断が割れる場合、または修正すると運用方針を決めることになる場合は、自動修正せず human-decision または needs-workflow にする。
Severity
blocking: 公開、運用、またはworkflow実行を止めるべき問題。high: 次に該当skillやagentを使う前に直すべき問題。medium: 近いうちに直すと混乱を減らせる問題。low: 表記、整理、重複削減など。
出力形式
固定のaudit reportテンプレートを会話上に出さない。ユーザーが見たいのは修正後のdiffであるため、最終出力は修正差分の要約と見るべきポイントへ寄せる。
保存用のaudit reportをユーザーが求めた場合だけ、目的に合う範囲で次を残す。
- audit対象と未確認範囲
- finding、severity、根拠、影響、推奨修正
- 適用した自動修正
- 人間判断または別workflowへ戻す項目
- 推奨更新順
禁止事項
auto-fixableと分類できない実装修正、skill修正、agent修正、検証実行を始めない。- secretsや本番ログを本文へ複製しない。
- ローカル環境にだけ存在するpathを公開前提の推奨として固定しない。
- severityを曖昧にせず、影響と戻り先を明記する。
- ユーザー承認なしに破壊的操作、削除、整形、移動を行わない。
- 人間判断が必要なfindingを、表記修正として扱って自動修正しない。
完了報告
最後は、修正差分を見る人に必要な情報だけを自然に返す。
- 修正したファイルと、何を変えたか。
- 人間がdiffで特に見るべきポイント。
- 自動修正しなかったfinding、人間判断、戻り先。
- 未確認範囲が結果解釈に影響する場合だけ、その範囲。
修正がない場合は、主要finding、見るべき証跡、次の戻り先だけを短く返す。
Source: tumbling-dice/project-management-skills — distributed by TomeVault.