simplify-and-harden

エージェントスキル：シンプル化と堅牢化

インストール

gh skill install pskoett/pskoett-skills simplify-and-harden

CI のみで実行する場合は、次を使用します。

gh skill install pskoett/pskoett-skills simplify-and-harden-ci

Agent Skills CLI を使った代替方法：

npx skills add pskoett/pskoett-skills/skills/simplify-and-harden
npx skills add pskoett/pskoett-skills/skills/simplify-and-harden-ci

メタデータ

フィールド	値
スキル ID	simplify-and-harden
バージョン	0.1.0
トリガー	完了後のフック
作成者	Peter Skøtt Pedersen
カテゴリー	コード品質 / セキュリティ
優先度	推奨

背景と理念

コーディングエージェントがタスクを完了した時点では、問題、解決策、そしてその過程で選択したトレードオフについて、文脈を最も深く理解しています。この文脈はすぐに薄れていきます――次のタスクが始まれば、状況は一新されます。Simplify & Harden は、この文脈が最も豊かな時間を活用し、エージェントが次に進む前に、目的を絞った 2 回のレビューを行います。

ほとんどのエージェントはチケットを解決して、そこで止まります。このスキルは「完了」を「きちんと完了」に変えます。

運用の理念は、次に進む前に意図的に「新鮮な目」で自己レビューを行うことです。新たに書いたコードと、タスクで変更した既存のコードをすべて注意深く読み直し、明らかなバグやエラー、分かりにくいロジック、脆弱な前提、命名上の問題、見落とした堅牢化の機会がないかを厳しく確認します。目的はスコープを広げたり、解決策を書き直したりすることではありません。変更の意図をまだ覚えているうちに、文脈が最も豊かな状態を活用し、規律ある初回レビューを行うことです。

独立したレビューとの併用

このスキルは完了後に行う自己レビューであり、独立したレビューの代わりにはなりません。

推奨する流れ：

1. タスクを実装します。
2. Simplify & Harden を実行し、整理、堅牢化を行い、分かりにくい判断を文書化します。
3. 深刻度順に指摘事項をまとめる独立したレビューを実行します。
4. 両方のレビューへの対応が済んでから、マージします。

両者の見解が異なる場合は、独立したレビューの指摘を外部の承認基準として扱い、修正するか、指摘事項を明示的に受け入れない判断をしてください。

必要に応じた独立レビュー

大規模な変更やリスクの高い変更では、文脈を持たない汎用サブエージェントを使用します。 名前付きのエージェントプリセットは必要ありません。変更ファイル一覧、差分、承認済みの計画または受け入れ基準、関連する検証の証拠を渡します。対象範囲のコードを直接読み、ファイルを編集せずに指摘事項を報告するよう依頼してください。ホストが対応している場合は、ツールを読み取り専用に制限します。対応していない場合は、その制約を依頼内容に明記します。Copilot では、チャットで同じ範囲の独立レビューを依頼してください。

複雑さとセキュリティのレビューには、以下の Simplify and Harden チェックリストを使用します。また、提示された要件をすべて実装と照合します。不足している機能、誤った動作、不完全なパスやエラー処理、API とレスポンスの契約、テストカバレッジ、未検証の受け入れ基準を確認してください。仕様との不一致は、不足、誤り、不完全、未テストに分類します。

指摘事項は深刻度順に並べ、ファイルと行（または「未実装」）、カテゴリー、具体的な根拠、関連する仕様の参照または攻撃ベクトル、具体的な修正方法を記載するよう求めます。スコープ外の所見は分けて記載し、対象範囲内の指摘がない場合はその旨を明示します。レビュー担当者は報告のみを行い、修正は既存の承認ルールと再検証ルールに従って実装担当エージェントが行います。

関連するすべての観点は、1 人のレビュー担当者が確認できます。スコープやリスクに応じて必要な場合に限り、レビューを分割してください。自動的に 3 つのエージェントに分ける必要はありません。独立レビューを利用できない場合は、その制約を報告してください。自己レビューは、独立したマージ承認の代わりにはなりません。

トリガー条件

以下の条件がすべて満たされると、スキルが自動的に起動します。

• エージェントが主要なコーディングタスクを完了している
• エージェントがタスクの完了を示している（終了コード 0、PR の準備完了、または同等の状態）
• 差分に重要なコード変更が含まれている（定義は以下を参照）
• このタスクでスキルがまだ実行されていない（再入ループがない）

重要なコード変更の定義

次のいずれかの条件を満たす場合、差分を重要な変更として扱います。

1. 少なくとも 1 つの実行可能なソースファイル（例：*.ts、 *.tsx、*.js、*.jsx、*.py、*.go、*.rs、*.java、*.cs、 *.rb、*.php、*.swift、*.kt、*.scala、*.sh）に触れており、かつ 次のいずれかを含む場合：
   • 実行可能なソースファイル内で、コメントでも空白でもない変更行が 10 行以上ある、または
   • 影響の大きいロジック変更が少なくとも 1 つある（認証／認可チェック、入力検証、データアクセス／クエリロジック、外部コマンドの実行、ファイルパスの処理、ネットワークリクエストの処理、または並行制御）。
2. 誰が操作できるか、何が実行されるか、何がデプロイされるか、またはどの保護策が適用されるかを変えるような形で、設定、ワークフロー、権限、デプロイ、またはセキュリティポリシーを変更している。

差分がドキュメントのみ、影響の小さい設定のみ、コメントのみ、書式のみ、生成された成果物のみ、またはテストのみの場合は、重要な変更ではない（false）として扱います。

次の場合、スキルは起動しません。

• エージェントが失敗した、または中断された
• 変更がドキュメントのみ
• 変更がテストのみ
• 変更が生成ファイル（ロックファイル、ビルド成果物）
• ユーザーが --no-review または同等のフラグで明示的にスキップした

対象範囲の制約

絶対ルール：このタスクで変更したファイルのみを編集してください。

エージェントは次のことをしてはいけません。

• 変更していない隣接コードをリファクタリングする
• 「ついでに」差分の範囲外の改善を行う
• 新しい依存関係やアーキテクチャの変更を導入する
• 他の場所で気付いたパターンを根拠に、推測に基づく修正を行う

エージェントは、対象範囲外の懸念事項には手を加えず、概要の出力で指摘する必要があります。

予算上限：

• 追加変更の最大量：元の差分の 20%（変更行数で測定）
• 最大実行時間：60 秒（設定可能）
• いずれかの上限に達した場合、エージェントは作業を停止し、budget_exceeded フラグを付けて現状を出力します

パス 1：簡素化

目的： 実装によって生じた不要な複雑さを減らします。

基本方針：再構成ではなく、簡素化すること。 このパスの主な目的は、動作を変えないことが明確な、軽微なクリーンアップです。リファクタリングは例外であり、原則ではありません。

新鮮な視点での確認（必須）： このパスで編集を始める前に、このタスクで追加または変更したコードをすべて、新鮮な視点で読み直し、明らかなバグや誤り、分かりにくいロジック、脆弱な前提、命名上の問題、見落としている堅牢化の機会を積極的に探してください。

エージェントは自分の作業を見直し、次のように考えます。

「解決策全体を理解した今、これをもっと簡潔に表現する方法はないだろうか？」

レビューのチェックリスト

1. 不要なコードや足場コード -- デバッグログ、コメントアウトした試行コード、未使用のインポート、反復作業中に作成した一時変数が残っていませんか？削除してください。

2. 明確な命名 -- 関数名、変数名、パラメーター名は、初めて読む人にも意味が伝わりますか？実装中は分かりやすかった名前でも、後から読むと分かりにくいことがよくあります。名前を変更してください。

3. 制御フロー -- 入れ子になった条件分岐をフラットにできますか？深いネストを早期リターンに置き換えられますか？単純化できるブール式はありませんか？整理してください。

4. API の公開範囲 -- 必要以上に公開していませんか？パブリックなメソッドや関数をプライベートにできますか？公開範囲を縮小してください。

5. 過剰な抽象化 -- 現在のスコープでは正当化できないクラス、インターフェース、ラッパー関数を作成していませんか？エージェントは過剰に設計する傾向があります。指摘はしてください。ただし、改善効果が大きくない限り、構造を変更してはいけません。

6. 統合の機会 -- 1か所にまとめられるロジックを、複数の関数やファイルに分散していませんか？指摘はしてください。ただし、重複が著しく、統合がすっきり行える場合に限り、リファクタリングを提案してください。

簡素化のアクション

各指摘について、エージェントは次のように分類します。

• 動作を維持する修正（証明可能な未使用インポートや、タスクで作成された不要なコードの削除など） -- 予算内であれば自動的に適用します。
• 外部から観察できる変更、または不確実な変更（命名、制御フロー、公開範囲、API、ポリシー、権限、デプロイ、セキュリティの動作を含む） -- 差分が小さくても、人間の承認を得るために提案します。
• リファクタリング（統合、構造変更、抽象化の変更） -- エージェントが真に必要、または効果が大きいと判断した場合にのみ提案します。リファクタリングはデフォルトのアクションではありません。判断基準は、「現状は単に不完全なのではなく、明らかに間違っている」とシニアエンジニアが考えるかどうかです。

リファクタリング停止フック（必須）：

エージェントが変更をリファクタリングと分類した場合、対話形式のプロンプトを必ず表示します。エージェントは次のことを行う必要があります。

1. 変更内容とその理由を説明する
2. 変更前と変更後（または構造変更の明確な説明）を示す
3. 適用する前に、人間からの明示的な承認を待つ

エージェントは複数のリファクタリング提案をまとめて提示しません。人間が個別に承認、却下、または修正できるよう、各リファクタリングを1件ずつ提示します。

[simplify-and-harden] Refactor proposal (1 of 2):

  I want to merge duplicated validation logic from handleCreate() and 
  handleUpdate() into a shared validatePayload() function.

  Why: Both functions validate the same fields with identical rules.
  The duplication was introduced because I built handleUpdate as a 
  copy of handleCreate during implementation.

  Files affected: src/api/handler.ts (lines 34-67)
  Estimated diff: -22 lines, +14 lines

  [approve] [reject] [show diff] [skip all refactors]

人間が「すべてのリファクタリングをスキップ」を選択した場合、エージェントは残りのリファクタリング提案をスキップし、Harden パスに進みます。スキップされたリファクタリングも、出力サマリーにステータス skipped_by_user の flagged として表示されます。

動作を維持すると証明された変更のみ、停止フックを起動しません。分類ラベルが外部から観察できる動作に優先することはありません。変更名、分岐の書き換え、公開範囲の縮小は、外部に影響を及ぼす可能性があり、その影響が不確かな場合は承認が必要です。

パス 2：強化

目的： エージェントがまだコードの意図を理解しているうちに、セキュリティとレジリエンスの抜けを解消します。

エージェントは自分の作業をレビューし、次のように問いかけます。

「悪意のある人物がこのコードを見たら、どのようなことを試みるだろうか？」

レビューチェックリスト

1. 入力の検証 -- すべての外部入力（ユーザー入力、API パラメーター、ファイルパス、環境変数）は使用前に検証されていますか？ 型変換の問題、境界チェックの欠如、制限のない文字列長がないか確認してください。

2. エラー処理 -- catch ブロックは適切に限定されていますか？ 機密データを漏らさず、コンテキストを添えてエラーを記録していますか？ 例外を握りつぶしていませんか？

3. インジェクションの攻撃経路 -- 外部入力から文字列を構築するコードにおいて、SQL インジェクション、XSS、コマンドインジェクション、パストラバーサル、テンプレートインジェクションがないか確認してください。

4. 認証と認可 -- 新しいエンドポイントや関数で認証が適用されていますか？ 権限チェックは存在し、正しく機能していますか？ 権限昇格のリスクはありませんか？

5. シークレットと認証情報 -- ハードコードされたシークレット、API キー、トークン、パスワードはありませんか？ 接続文字列はパラメーター化されていますか？ ログ出力に認証情報が含まれていないか確認してください。

6. データの露出 -- エラー出力、ログ、API レスポンスから、内部状態、スタックトレース、データベーススキーマ、PII が漏れていませんか？

7. 依存関係のリスク -- エージェントは新たな依存関係を導入しましたか？ 導入した場合、それらは適切に保守され、適切にバージョン管理され、既知の脆弱性がありませんか？

8. 競合状態と状態管理 -- 並行処理コードの場合、共有リソースは適切に同期されていますか？ TOCTOU（time-of-check-to-time-of-use）脆弱性はありませんか？

アクションの強化

各検出事項について、エージェントは次のように分類します。

• パッチ（検証チェックの追加、出力のエスケープ、ハードコードされたシークレットの削除） -- 承認済みの受け入れ条件ですでに求められており、対象を絞った検証で結果を証明できる場合に限り、自動で適用します。それ以外の場合は人間の承認を求めます
• セキュリティリファクタリング（認証フローの再構成、脆弱なパターンを新しい手法に置き換えること、データ処理アーキテクチャの変更） -- 続行する前に、必ず人間の承認が必要です

Simplify パスと同じ Refactor Stop Hook がここでも適用されます。セキュリティリファクタリングは、深刻度と攻撃経路の情報を追加して、個別に提示します。

[simplify-and-harden] Security refactor proposal:

  The new /admin/export endpoint inherits base authentication but has 
  no role-based access check. Any authenticated user can trigger a 
  full data export.

  Severity: HIGH
  Vector: Privilege escalation
  
  Proposed fix: Add role guard requiring 'admin' role before the 
  handler executes. This changes the middleware chain for this route.

  Files affected: src/api/routes/admin.ts (line 12)
  Estimated diff: +8 lines

  [approve] [reject] [show diff] [skip all security refactors]

• 重大としてフラグ付け -- 人間の入力なしでは安全にパッチを適用できない検出事項（承認の有無にかかわらず出力に記載）
• 助言としてフラグ付け -- 現在は脆弱性ではない、セキュリティ強化の機会

予算が限られている場合は、セキュリティパッチ（リファクタリングではないもの）を簡素化の変更より優先します。

パス 3：文書化（マイクロパス）

目的： エージェントが変更の理由をまだ覚えているうちに、明白でない判断を記録します。

これは意図的に軽量化したもので、文書化パスではなく、判断の記録のみを行います。

ルール

• 「なぜこれがあるのか？」を考えるのに 5 秒以上かかるロジックには、判断を説明する1行コメントを追加します
• 回避策やハックには、背景を記したコメントを追加し、できれば削除条件を示す TODO も追加します
• パフォーマンスに影響する選択には、明白な代替案ではなく現在の方法を選んだ理由を記します
• 上限：タスクあたり追加するコメントは 5 件まで。文書化の一大作業ではありません。

パス 4：再検証

完了を通知する前に、再検証が必須です。

1. Simplify & Harden がファイルを変更した場合、その編集を対象とする既存のテスト、チェック、リンター、または動作に関する受け入れ確認のうち、最小限のものを再実行します。
2. 編集がなかった場合、直前の verify-gate の証跡がレビュー対象の差分をカバーしている限り、それを再利用できます。
3. 検証に失敗した場合、診断情報をもとに実装に戻ります。成功したと通知してはいけません。
4. 適用可能な検証が存在しない場合は、not-run を記録し、review_followup_required: true を設定して、タスクが完全に検証済みだと主張してはいけません。

出力スキーマ

このスキルは、タスク出力に追加される構造化されたサマリーを生成します。

simplify_and_harden:
  version: "0.1.0"
  task_id: "<original task ID>"
  execution:
    mode: "interactive"
    mode_source: "auto_detected"  # "auto_detected", "config", "env_override"
    human_present: true
  scope:
    files_reviewed: ["src/api/handler.ts", "src/utils/validate.ts"]
    original_diff_lines: 142
    additional_changes_lines: 18
    budget_exceeded: false

  simplify:
    applied:
      - file: "src/api/handler.ts"
        line: 45
        type: "consolidation"
        category: "refactor"
        approval: "approved_by_user"
        description: "Merged duplicated validation logic from handleCreate and handleUpdate into shared validatePayload function"
    flagged:
      - file: "src/utils/validate.ts"
        type: "over-abstraction"
        category: "refactor"
        approval: "skipped_by_user"
        description: "ValidationStrategy interface may be unnecessary -- only one implementation exists. Consider inlining if no additional strategies are planned."
        confidence: "medium"
    cosmetic_applied:
      - file: "src/api/handler.ts"
        line: 12
        type: "dead_code"
        description: "Removed unused import of deprecated AuthHelper"

  harden:
    applied:
      - file: "src/api/handler.ts"
        line: 62
        type: "input_validation"
        severity: "high"
        description: "Added bounds check on pageSize parameter -- previously accepted arbitrary integers"
    flagged_critical:
      - file: "src/api/handler.ts"
        type: "authorization"
        description: "New /admin/export endpoint inherits base auth but no role check -- any authenticated user can access it. Requires human decision on role policy."
    flagged_advisory:
      - file: "src/utils/validate.ts"
        type: "error_handling"
        description: "Catch block on L31 logs full request body which may contain PII in production"

  document:
    comments_added: 2
    locations:
      - file: "src/api/handler.ts"
        line: 78
        comment: "// Pagination uses cursor-based approach instead of offset -- offset breaks when items are deleted between pages"
      - file: "src/api/handler.ts" 
        line: 93
        comment: "// WORKAROUND: Legacy API returns dates as strings without timezone. Assuming UTC until migration completes (see TICKET-1234)"

  verification:
    command: "npm test -- src/api/handler.test.ts"
    result: "pass" # pass | fail | not-run
    evidence: "Targeted handler tests passed after review edits"

  learning_loop:
    target_skill: "self-improvement"
    log_file: ".learnings/LEARNINGS.md"
    candidates:
      - pattern_key: "simplify.dead_code"
        pass: "simplify"
        finding_type: "dead_code"
        severity: "low"
        source_file: "src/api/handler.ts"
        source_line: 12
        suggested_rule: "Remove dead code and unused imports before finalizing a task."
      - pattern_key: "harden.input_validation"
        pass: "harden"
        finding_type: "input_validation"
        severity: "high"
        source_file: "src/api/handler.ts"
        source_line: 62
        suggested_rule: "Validate and bound-check external inputs before use."
    recurrence_window_days: 30
    promotion_threshold:
      min_occurrences: 3
      min_distinct_tasks: 2

  summary:
    simplify_applied: 1
    simplify_cosmetic_applied: 1
    simplify_flagged: 1
    simplify_rejected_by_user: 0
    simplify_skipped_by_user: 1
    harden_applied: 1
    harden_flagged_critical: 1
    harden_flagged_advisory: 1
    harden_rejected_by_user: 0
    comments_added: 2
    total_additional_lines: 18
    budget_utilization: "12.7%"
    human_prompts_shown: 3
    human_prompts_approved: 1
    human_prompts_rejected: 0
    human_prompts_skipped: 1
    human_prompts_timed_out: 1
    learning_candidates: 2
    learning_promotions_recommended: 1
    verification_result: "pass"
    review_followup_required: true

未解決の指摘が残っている場合（critical/advisory フラグ、スキップされたリファクタリング提案、またはタイムアウトしたリファクタリング提案）、budget_exceeded が true の場合、または検証結果が pass でない場合は、review_followup_required を true に設定します。フォローアップが不要な場合に限り、false に設定します。

自己改善との連携（学習ループ）

Simplify & Harden は、繰り返し発生する品質およびセキュリティ上の指摘を self-improvement スキルに取り込み、繰り返される問題を持続的なプロンプトルールにできるようにします。

各実行後：

1. 各指摘を pattern_key に正規化します。
   • Simplify の例：simplify.dead_code、simplify.naming、simplify.control_flow
   • Harden の例：harden.input_validation、harden.authorization、harden.error_handling
2. これらのパターン候補を simplify_and_harden.learning_loop.candidates に出力します。
3. 候補を self-improvement に引き継ぎ、.learnings/LEARNINGS.md のエントリを記録または更新します（重複する単発のメモは作成しません）。
4. 30 日間に、2 つ以上の異なるタスクで 3 回以上発生した場合、候補に昇格準備完了のマークを付けます。
5. 昇格準備が整ったパターンを、エージェントのコンテキスト／システムプロンプトファイル（CLAUDE.md、AGENTS.md、.github/copilot-instructions.md など）に反映し、同じ問題の再発を減らします。

これにより、Simplify & Harden はタスクごとのクリーンアップと強化に専念し、self-improvement がタスクをまたいだ記憶と昇格を担います。

実行モデル

このスキルは、人間がその場でリファクタリングを承認できる、一般的なコーディングエージェントのセッション向けです。

動作：

• リファクタリングの提案は、明確な理由とともに一つずつ提示されます。
• エージェントは一時停止し、[approve]、[reject]、[show diff]、または [skip all refactors] を待ちます。
• 動作が確実に維持される修正と、受け入れ基準に基づくセキュリティパッチのみ、自動的に適用されます。

CI パイプラインやヘッドレス自動化には、simplify-and-harden-ci を使用してください。

エージェントコンテキストファイルの参照

このスキルを有効にするには、エージェントのコンテキストファイルでこのスキルを参照してください。

エージェント別のコピー＆ペースト用スニペットは references/agent-context-snippets.md にあります。 コンテキストを簡潔に保つため、現在使用しているエージェント用のスニペットのみを読み込んでください。

エージェントとの連携における基本的な不変条件：

1. スコープの固定 -- 現在のタスクで変更されたファイルのみを対象にします
2. 予算上限 -- 追加差分は最大 20%
3. シンプルさを優先する姿勢 -- クリーンアップをデフォルトとし、リファクタリングは例外とします
4. リファクタリング停止フック -- 構造的な変更には必ず人間の承認が必要です
5. 4 つのフェーズ -- シンプル化、強化、文書化、再検証の順に実施します
6. 編集後の検証 -- レビューによる編集後は、該当するチェックを再実行します
7. 構造化された出力 -- 適用、承認、却下、フラグ付け、検証済みの項目をサマリーにまとめます

注意：自律性の高いモードでは、承認を求めるために確実に一時停止できないエージェントもあります。本番利用の前に、この動作を検証してください。

エージェントの互換性

このスキルは、タスクベースのワークフローに従うあらゆるコーディングエージェントで動作するよう設計されています。特定のエージェントフレームワークや製品には依存しません。

プログラムによる連携（スキル／フック API を備えたエージェント）：

• Claude Code、GitHub Copilot Workspace、Codex、Opencode、OpenClaw、Cursor Agent、Windsurf、Aider、SWE-Agent、OpenHands、Devin、およびタスク完了ライフサイクルイベントを公開するあらゆるエージェント

プロンプトによる連携（正式なスキル API を持たないチャットベースのエージェント）：

• タスク後の指示を受け入れる、LLM ベースのあらゆるコーディングアシスタント -- エージェントが完了を通知した後、スキルのロジックをフォローアッププロンプトとして挿入できます

出力スキーマは、エージェントに依存しない YAML です。利用するツールは、構造化されたサマリーを解析するだけで済みます。

連携に関する注記

このスキルはエージェントに依存しません。タスク完了ライフサイクルイベントを公開するあらゆるコーディングエージェントにフックできます。以下の例は汎用的なものです。使用するエージェント固有の API に合わせて調整してください。

エージェントとの統合

このスキルは、エージェントのタスク完了ライフサイクルにフックします。推奨される統合パターンは次のとおりです。

agent.on('task:complete', async (context) => {
  if (context.diff.isNonTrivial() && !context.flags.includes('no-review')) {
    const result = await skills.run('simplify-and-harden', {
      diff: context.diff,
      files: context.modifiedFiles,
      budget: { maxLines: context.diff.linesChanged * 0.2, maxTime: 60000 }
    });
    context.appendOutput(result.summary);
  }
});

このスキルをサポートするエージェントは、次のインターフェースを実装してください。

• 完了したタスクで生成された差分へのアクセス
• 変更されたファイルと、その全内容の一覧
• 対話型プロンプトを提示する機能（対話型モード用）
• 構造化された要約を出力するためのチャネル（stdout、PR コメント、または同等のもの）

プロンプトベースの統合

プログラムによるスキルフックをサポートしていないエージェント（Claude Code、Cursor、Copilot Chat などのチャットベースのコーディングエージェント）では、このスキルをタスク完了後のプロンプトインジェクションとして実装できます。

After completing the task, run the Simplify & Harden review:
1. Review only the files you modified
2. Simplify: Your default action is cleanup. Apply only changes proven
   behavior-preserving, such as removing a task-created unused import.
   Naming, control-flow, visibility, API, policy, permission, deployment, and
   security changes require approval when their effect is observable or
   uncertain. Refactoring is NOT the default.
3. Harden: Check for input validation gaps, injection vectors, auth issues, 
   exposed secrets, and error handling problems. Apply a patch directly only
   when the approved acceptance contract requires it and a targeted check can
   verify it. Otherwise describe the issue with severity and ask for approval.
4. Document: Add up to 5 comments on non-obvious decisions.
5. Re-verify: Run the smallest existing checks that cover all review edits.
6. Output a summary of what you changed, what you flagged, what you left
   alone, and the verification evidence.

CI パイプライン版

GitHub Actions またはその他の CI／ヘッドレス環境では、simplify-and-harden-ci を実行します。

設定

# Example configuration (adapt path to your agent's config format)
# e.g., .agent/skills.yaml, .claude/skills.yaml, .cursor/skills.yaml
simplify-and-harden:
  enabled: true
  budget:
    max_diff_ratio: 0.2        # Max additional changes as ratio of original diff
    max_time_seconds: 60       # Hard time limit
  simplify:
    enabled: true
    auto_apply_behavior_preserving: true
    refactor_requires_approval: true  # ALWAYS true -- cannot be disabled
  harden:
    enabled: true
    auto_apply_acceptance_backed_patches: true
    refactor_requires_approval: true  # ALWAYS true -- cannot be disabled
  document:
    enabled: true
    max_comments: 5
  stop_hook:
    mode: "interactive"
    show_diff_preview: true
    allow_skip_all: true
    timeout_seconds: 300       # 5 min -- human is at the keyboard
    timeout_action: "flag"     # Assume they stepped away, don't discard
  skip_patterns:               # Glob patterns to exclude from review
    - "**/*.test.*"
    - "**/*.spec.*"
    - "**/migrations/**"

設計上の決定

なぜ継続的な実施ではなく、完了後に行うのですか？ 実装中に継続してレビューするとフィードバックループが発生し、エージェントの作業が遅くなるうえ、改善と再複雑化を繰り返す可能性があります。完了後に実施すれば、エージェントは安定したコードベースを基準にレビューできます。

なぜリファクタリングを優先せず、簡素化を優先するのですか？ エージェントはリファクタリングを好みます。コードを「改善」する許可を与えると、構造を変更します。しかし、タスク完了後の改善の大半は見た目上のものです。不要なインポート、不適切な名前、必要以上に深い条件分岐などです。これらは、ほぼリスクなしで価値の 80% 以上をもたらします。リファクタリングには実際のリスクがあり、バグを持ち込んだり、テストを壊したり、差分を膨らませたりする可能性があります。簡素化をデフォルト、リファクタリングを例外とすることで、このスキルは予想外の書き換えを避けながら、一貫した価値を提供します。リファクタリングの基準は「少し改善できる」ではなく、「本当に間違っている」であるべきです。

なぜ予算を設けるのですか？ 制約がなければ、エージェントはレビューの機会を際限のないリファクタリングの許可として使います。20% ルールによって、このスキルの目的を明確に保てます。作成したものを改善し、作り直さないようにします。

なぜ簡素化と堅牢化を分けるのですか？ それぞれ異なる考え方が必要だからです。簡素化では「意図を最も明確に表現できているか？」と問い、堅牢化では「どのように悪用される可能性があるか？」と問います。これらを混同すると、どちらも中途半端な結果になります。また、順番に実行することで、予算が厳しい場合にセキュリティ修正を優先できます。

なぜドキュメントのマイクロパスがあるのですか？ エージェントは、促されないと判断の理由を記録するのが非常に苦手です。エージェントが生成したコードをレビューする人間からは、選択の「理由」を理解することが最大の障壁だと一貫して報告されています。5 件のコメントは、レビュー時間を大幅に短縮できることを考えれば、わずかなコストです。

今後の検討事項

• チームごとの調整：チームがレビューチェックリストの重み付けを設定できるようにします（例：「命名よりもインジェクションの攻撃経路を重視する」）
• 差分を考慮したコンテキスト読み込み：大規模なコードベースでは、プロジェクト全体ではなく、差分に関連するファイルとシンボルだけをインテリジェントに読み込みます
• スキル間の連携：Simplify & Harden の要約を使って、意味のある PR 説明を自動生成する「PR Description」スキルに連携できます