--- name: harness-engineering description: ハーネスエンジニアリングスキル。AIエージェントの品質と信頼性を高めるための手法論。Ralph Wiggum Loop（自己レビュー）、Golden Principles（機械的ルール）、Progressive Disclosure（段階的情報開示）、Mechanical Enforcement（不変条件強制）、Garbage Collection（技術的負債解消）を統合し、継続的な品質改善を実現。 license: MIT tags: [quality, reliability, best-practices] metadata: skill-version: "1.0.0" created-by: pi-skill-system based-on: OpenAI Harness Engineering --- # Harness Engineering AIエージェントの品質と信頼性を体系的に高めるための手法論。OpenAIのハーネスエンジニアリングの概念を統合し、継続的な品質改善を実現する。 **主な機能:** - Ralph Wiggum Loopによる自己レビューサイクル - Golden Principlesによる機械的ルールの適用 - Progressive Disclosureによる段階的情報開示 - Mechanical Enforcementによる不変条件の強制 - Garbage Collectionによる技術的負債の解消 --- ## 概念フレームワーク ### 5つの柱 ``` +------------------+ +-------------------+ +---------------------+ | Ralph Wiggum | | Golden | | Progressive | | Loop | | Principles | | Disclosure | | (自己レビュー) | | (機械的ルール) | | (段階的情報開示) | +--------+---------+ +--------+----------+ +----------+----------+ | | | v v v +-----------------------------------------------------------------------+ | Harness Engineering Core | | | | 目的: AIエージェントの品質・信頼性・保守性を継続的に向上させる | +-----------------------------------------------------------------------+ | | | v v v +--------+---------+ +--------+----------+ +----------+----------+ | Mechanical | | Garbage | | Quality | | Enforcement | | Collection | | Metrics | | (不変条件強制) | | (技術的負債解消) | | (品質指標) | +------------------+ +-------------------+ +---------------------+ ``` --- ## 1. Ralph Wiggum Loop（自己レビューループ） ### 概念 「自分の仕事を自分でレビューする」継続的な改善サイクル。外部レビューに頼らず、自己評価と修正を繰り返すことで品質を高める。 ### 名前の由来 シンプソンズのRalph Wiggumのように、一見単純なアプローチが実は深い洞察を含むことを示唆。 ### サイクル構造 ``` +-------------+ +-------------+ +-------------+ | Produce | --> | Review | --> | Refine | | (作成) | | (確認) | | (改良) | +-------------+ +-------------+ +-------------+ ^ | +----------------------------------------+ (繰り返し) ``` ### 実践ガイドライン 1. **作成フェーズ** - 要件に基づいて成果物を作成 - 最初から完璧を目指さない（動くものをまず作る） - 段階的に詳細を追加 2. **確認フェーズ** - 自分の成果物を客観的に評価 - チェックリストを使用 - 「他の人が見たらどう思うか」の視点を持つ 3. **改良フェーズ** - 発見した問題を修正 - 改善案を実装 - 次のサイクルに向けた学習を記録 ### チェックリスト ``` 作成後の自己確認: [ ] 要件をすべて満たしているか [ ] 境界条件を考慮しているか [ ] エラーハンドリングは適切か [ ] ドキュメントは十分か [ ] テストは網羅的か ``` --- ## 2. Golden Principles（機械的ルール） ### 概念 判断の余地なく適用できる「機械的」なルール。一貫性を保証し、認知負荷を低減する。 ### 特徴 - **条件付きで適用**: 特定の条件で自動的に発動 - **例外なし**: ルールは絶対的に適用 - **明示的**: 曖昧さを許さない ### カテゴリ #### 2.1 品質ルール | ルールID | 条件 | アクション | |----------|------|-----------| | Q-001 | 関数が50行を超える | 分割を検討 | | Q-002 | 循環的複雑度が10を超える | 簡素化を検討 | | Q-003 | テストカバレッジが80%未満 | テスト追加が必要 | | Q-004 | TODOコメントが7日以上経過 | Issue化または削除 | #### 2.2 セキュリティルール | ルールID | 条件 | アクション | |----------|------|-----------| | S-001 | ユーザー入力を直接実行 | 必ずサニタイズ | | S-002 | パスワードを平文保存 | 必ずハッシュ化 | | S-003 | SQL文字列結合 | 必ずパラメータ化クエリ | | S-004 | 機密情報をログ出力 | 必ずマスクまたは削除 | #### 2.3 ドキュメントルール | ルールID | 条件 | アクション | |----------|------|-----------| | D-001 | 公開APIにコメントなし | JSDoc/docstringを追加 | | D-002 | READMEに使用例なし | 使用例を追加 | | D-003 | 設定項目に説明なし | 説明を追加 | | D-004 | 変更履歴がない | CHANGELOGを更新 | ### ルール適用フロー ``` +------------------+ | コード/成果物 | +--------+---------+ | v +--------+---------+ | 条件チェック | +--------+---------+ | +----+----+ | 条件一致?| +----+----+ | Yes / \ No / \ v v +-----+--+ +--------+ | ルール | | 次へ | | 適用 | +--------+ +---------+ ``` --- ## 3. Progressive Disclosure（段階的情報開示） ### 概念 情報を一度にすべて提供せず、必要なタイミングで必要な量だけ開示する手法。認知負荷を管理し、効率的な理解を促進。 ### レイヤー構造 ``` +------------------------------------------+ | Layer 4: 詳細ドキュメント | <- 必要な時だけ | (APIリファレンス、実装詳細) | +------------------------------------------+ | Layer 3: 使用ガイド | <- 実践する時 | (チュートリアル、サンプル) | +------------------------------------------+ | Layer 2: 概要説明 | <- 理解を深める時 | (目的、使い方、注意点) | +------------------------------------------+ | Layer 1: 要約 | <- 最初に見る | (1-2文で何をするものか) | +------------------------------------------+ ``` ### 実践パターン #### 3.1 コメントにおける適用 ```typescript // Layer 1: 1行要約 // ユーザーをデータベースから取得する // Layer 2: 詳細説明（必要時） // 指定されたIDに基づいてユーザー情報を取得する。 // キャッシュが有効な場合はキャッシュから返す。 // Layer 3: 使用例（さらに詳細が必要な場合） // 使用例: // const user = await getUser('123'); // console.log(user.name); ``` #### 3.2 ドキュメントにおける適用 ```markdown ## getUser - ユーザー取得 <- Layer 1: 要約 指定定IDのユーザーを取得する。 ### パラメータ <- Layer 2: 概要 - id: ユーザーID（必須） ### 戻り値 - User オブジェクト ### 詳細 <- Layer 3: 詳細 キャッシュ戦略、エラーハンドリングの詳細... ### 実装ノート <- Layer 4: 実装詳細 内部的な実装についての技術的な説明... ``` ### 情報開示の判断基準 | 状況 | 開示レベル | |------|-----------| | 最初の参照 | Layer 1（要約のみ） | | 使用を検討中 | Layer 2（概要追加） | | 実装を開始 | Layer 3（詳細追加） | | トラブルシューティング | Layer 4（全情報） | --- ## 4. Mechanical Enforcement（不変条件の強制） ### 概念 システムが常に満たすべき「不変条件」を定義し、これを機械的に強制する仕組み。バグや品質低下を自動的に検出・防止する。 ### 不変条件のタイプ #### 4.1 前提条件（Preconditions） 実行前に満たすべき条件。 ``` 例: - 関数呼び出し時: 引数がnullでない - ファイル読み込み時: ファイルが存在する - DB接続時: 接続が確立されている ``` #### 4.2 事後条件（Postconditions） 実行後に満たすべき条件。 ``` 例: - ソート関数: 結果が昇順である - 保存関数: データが永続化されている - 認証関数: セッションが有効である ``` #### 4.3 不変条件（Invariants） 常に満たすべき条件。 ``` 例: - スタック: 要素数が負にならない - 口座残高: 引き出し額 <= 残高 - セッション: 有効期限内またはnull ``` ### 強制メカニズム ``` +----------------+ +----------------+ +----------------+ | 静的解析 | | ランタイム | | テスト | | (TypeScript, | | (assertion, | | (unit, | | ESLint等) | | validation) | | integration) | +-------+--------+ +-------+--------+ +-------+--------+ | | | v v v +---------------------------------------------------------------+ | 不変条件チェック | +---------------------------------------------------------------+ | | | v v v [即座に検出] [実行時に検出] [テスト時に検出] ``` ### 実装パターン #### アサーション ```typescript // 前提条件の強制 function divide(a: number, b: number): number { console.assert(b !== 0, '除数は0以外である必要がある'); return a / b; } // 事後条件の強制 function sort(arr: number[]): number[] { const result = [...arr].sort((a, b) => a - b); // 不変条件チェック for (let i = 1; i < result.length; i++) { console.assert(result[i-1] <= result[i], '結果は昇順である必要がある'); } return result; } ``` #### 型による強制 ```typescript // 不変条件を型で表現 type NonEmptyString = string & { __brand: 'NonEmptyString' }; type PositiveNumber = number & { __brand: 'PositiveNumber' }; function createNonEmptyString(s: string): NonEmptyString { if (s.length === 0) throw new Error('空文字は許可されない'); return s as NonEmptyString; } ``` ### CI/CDでの強制 ```yaml # .github/workflows/quality.yml - name: Check Invariants run: | npm run type-check # 型レベルの不変条件 npm run lint # コーディング規約 npm run test # テストでの不変条件 npm run invariant-check # カスタム不変条件チェック ``` --- ## 5. Garbage Collection（技術的負債解消） ### 概念 技術的負債を定期的に特定・解消するプロセス。プログラミング言語のガベージコレクションのように、不要なものを自動的に回収する仕組みを目指す。 ### 技術的負債の分類 | カテゴリ | 説明 | 例 | |----------|------|-----| | コード負債 | コード品質の問題 | 複雑な関数、重複コード | | アーキテクチャ負債 | 設計上の問題 | 循環依存、不適切な責任分離 | | テスト負債 | テスト不足 | カバレッジ不足、テストなし | | ドキュメント負債 | 文書の不備 | 古いドキュメント、説明不足 | | 依存関係負債 | ライブラリの問題 | 脆弱性のある依存、古いバージョン | ### GCサイクル ``` +----------------+ +----------------+ +----------------+ | Mark | --> | Sweep | --> | Compact | | (負債の特定) | | (負債の解消) | | (最適化) | +----------------+ +----------------+ +----------------+ ^ | +--------------------------------------------+ (定期的に実行) ``` ### 実践プロセス #### 5.1 Mark（負債の特定） ```bash # 自動検出ツール - 静的解析: ESLint, SonarQube - 複雑度測定: escomplex, complexity-report - テストカバレッジ: jest --coverage, nyc - 依存関係チェック: npm audit, snyk ``` #### 5.2 Sweep（負債の解消） ``` 優先度付け基準: P0: セキュリティ脆弱性 -> 即時対応 P1: バグの原因 -> 1週間以内 P2: パフォーマンス影響 -> 2週間以内 P3: 可読性・保守性 -> 1ヶ月以内 P4: 将来の改善候補 -> バックログ ``` #### 5.3 Compact（最適化） ``` - リファクタリングの実施 - ドキュメントの更新 - テストの追加 - 依存関係の更新 ``` ### GCトリガー | トリガー | 頻度 | アクション | |----------|------|-----------| | 定期実行 | 週次/月次 | 定期的なスキャン | | リリース前 | 毎回 | リリース前チェック | | マージ時 | 毎回 | CI/CDパイプライン | | 閾値超過 | 動的 | 負債が基準を超えた時 | --- ## 統合ワークフロー ### 日々の実践 ``` +-------------------+ | タスク開始 | +--------+----------+ | v +--------+----------+ Golden Principles | ルール適用確認 | <-------------------+ +--------+----------+ | | | v | +--------+----------+ | | 成果物作成 | Ralph Wiggum | | (Progressive | Loop | | Disclosure適用) | | +--------+----------+ | | | v | +--------+----------+ | | 自己レビュー | --------------------+ +--------+----------+ | v +--------+----------+ Mechanical | 不変条件確認 | <--- Enforcement +--------+----------+ | v +--------+----------+ | テスト実行 | +--------+----------+ | v +--------+----------+ | 成果物完了 | +-------------------+ ``` ### 定期メンテナンス ``` 週次: - コード複雑度チェック - テストカバレッジ確認 - 小規模リファクタリング 月次: - 技術的負債の棚卸し（Garbage Collection） - 依存関係の更新確認 - ドキュメントの鮮度チェック 四半期: - アーキテクチャレビュー - 大規模リファクタリング計画 - プロセス改善の振り返り ``` --- ## チェックリスト ### 新規作成時 ``` [ ] Progressive Disclosure: 情報の階層化が適切か [ ] Golden Principles: 機械的ルールを満たしているか [ ] Mechanical Enforcement: 不変条件を定義・強制しているか [ ] Ralph Wiggum Loop: 自己レビューを実施したか ``` ### 定期レビュー時 ``` [ ] Garbage Collection: 技術的負債を特定・解消したか [ ] Golden Principles: ルールが最新か（追加・更新が必要か） [ ] Mechanical Enforcement: 不変条件が有効に機能しているか [ ] Progressive Disclosure: 情報の階層が適切か ``` --- ## リファレンス > 参照ファイルは作成予定です。現在は本文中の詳細セクションを参照してください。 - `references/ralph-wiggum-loop.md`（作成予定） - 自己レビューループの詳細 - `references/golden-principles.md`（作成予定） - 機械的ルール一覧 - `references/progressive-disclosure.md`（作成予定） - 段階的情報開示パターン - `references/mechanical-enforcement.md`（作成予定） - 不変条件強制の実装 - `references/garbage-collection.md`（作成予定） - 技術的負債解消プロセス --- ## 使用例 ### 例1: 新機能実装での適用 ``` 1. [Progressive Disclosure] - 1行要約: 「ユーザー認証を追加する」 - 詳細はレイヤーごとに追加 2. [Golden Principles] - Q-001: 関数は50行以内 - S-001: 入力は必ずサニタイズ 3. [Mechanical Enforcement] - 前提条件: ユーザーIDが有効 - 事後条件: セッションが作成される 4. [Ralph Wiggum Loop] - 作成 -> 確認 -> 改良 -> (繰り返し) 5. [Garbage Collection] - 実装後に負債チェック ``` ### 例2: コードレビューでの適用 ``` レビューチェックリスト: [Golden Principles] - [ ] 機械的ルールが適用されているか - [ ] 例外なく一貫して適用されているか [Progressive Disclosure] - [ ] コメントが階層化されているか - [ ] 必要な情報が適切なレベルで提供されているか [Mechanical Enforcement] - [ ] 不変条件が定義されているか - [ ] 不変条件が強制されているか [Garbage Collection] - [ ] 技術的負債が新規発生していないか - [ ] 既存の負債解消が必要か ``` --- ## ベストプラクティス 1. **小さく始める**: 1つの概念から導入し、徐々に拡大 2. **自動化する**: 手動プロセスは継続しない 3. **測定する**: 品質指標を定義し、改善を可視化 4. **文化を作る**: チーム全体で取り組む 5. **継続する**: 一度きりではなく、継続的な改善 --- ## トラブルシューティング | 問題 | 原因 | 解決策 | |------|------|--------| | ルールが守られない | ルールが複雑すぎる | ルールを簡素化・自動化 | | レビューが形骸化 | チェックリスト過多 | 重要な項目に絞る | | 負債が解消されない | 優先度が低い | 専用の時間を確保 | | 情報が過多 | Progressive Disclosure不適切 | 階層化を見直す | --- *このスキルはOpenAIのハーネスエンジニアリングの概念をベースに作成されました。* --- ## デバッグ情報 ### 記録されるイベント このスキルの実行時に記録されるイベント： | イベント種別 | 説明 | 記録タイミング | |-------------|------|---------------| | session_start | セッション開始 | pi起動時 | | task_start | タスク開始 | ユーザー依頼受付時 | | operation_start | 操作開始 | スキル実行開始時 | | operation_end | 操作終了 | スキル実行完了時 | | task_end | タスク終了 | タスク完了時 | ### ログ確認方法 ```bash # 今日のログを確認 cat .pi/logs/events-$(date +%Y-%m-%d).jsonl | jq . # 特定の操作を検索 cat .pi/logs/events-*.jsonl | jq 'select(.eventType == "operation_start")' # エラーを検索 cat .pi/logs/events-*.jsonl | jq 'select(.data.status == "failure")' ``` ### トラブルシューティング | 症状 | 考えられる原因 | 確認方法 | 解決策 | |------|---------------|---------|--------| | 実行が停止する | タイムアウト | ログのdurationMsを確認 | タイムアウト設定を増やす | | 結果が期待と異なる | 入力パラメータの問題 | paramsを確認 | 入力を修正して再実行 | | エラーが発生する | リソース不足 | エラーメッセージを確認 | 設定を調整 | ### 関連ファイル - 実装: `.pi/extensions/harness-engineering.ts` - ログ: `.pi/logs/events-YYYY-MM-DD.jsonl`