| name | harness-refine |
| description | This skill should be used when the user asks to "refine the harness", "self-improve the blueprint", "restructure .claude/ to match best practices", "audit harness configuration", or mentions "ハーネス補正", "ベストプラクティス準拠", "self-refine", "セルフリファイン", "ハーネス自己点検", "skill/agent/team 配置の見直し". Self-scores and refines the `.claude/` harness scaffolding (skills / agents / teams / rules) under `project-blueprint/` and `project-blueprint-en/` against refreshed official best practices, in lockstep across both language mirrors. Source code and `docs/`/`output/` content are out of scope. Runs a non-mutating Round 0 best-practice refresh, then self-score → self-improve → self-review for 2 fixed rounds, escalating to a human if not approved. Takes optional argument: /harness-refine <target-dir or instruction>
|
| argument-hint | <対象ディレクトリ or 補正指示(省略可)> |
| allowed-tools | Read, Glob, Grep, Bash(ls *, find *, wc *, diff *, grep *, git *), Edit, Write, WebFetch, WebSearch, Agent, mcp__plugin_context7_context7__resolve-library-id, mcp__plugin_context7_context7__query-docs |
| context | main |
Harness Refine — 自己強化型ベストプラクティス補正(Round 0 リフレッシュ + 2 ラウンド固定)
ハーネス構成(project-blueprint/ および project-blueprint-en/)を、
Claude Code 公式ベストプラクティス(毎回 Round 0 で再取得)と
constitution.md 7 原則 の両方を rubric として
自己採点 → 自己強化 → セルフレビュー を 2 ラウンド 回して構造補正するメタスキル。
実装コード、docs/ 内容、output/ 成果物、testreport/ 生データは対象外。テンプレート骨格のみを扱う。
自己強化メカニズム(本スキルの核)
本スキルは rubric を凍結せず、走るたびに自律的に強くなる。3 つの機構で実現する:
- Round 0 リフレッシュ(非破壊): 公式一次ソース(下記「ベストプラクティス基準ソース」)を
WebFetch / Context7 で再取得し、最新ガイダンスとの差分を 今回ラウンドの暫定採点基準に反映する。
訓練データだけで判断しない。
- adaptive ループ: 過去レポート(
output/reports/harness-refine/)を読み、
未解決課題と 2 回以上再発した指摘を抽出して優先補正対象へ昇格する(失敗をループでなく学習に変える)。
- rubric 自己進化: Round 0 で新しい公式ベストプラクティスを発見したら 新規採点項目を提案する。
ただし
constitution.md に触れる変更は自動採用せず、必ず人間承認を得る。
前提条件
| 参照 | 用途 | 改変 |
|---|
constitution.md(repo ルート) | 7 不変原則(rubric の上位条件) | ❌ 改変禁止 |
project-config.md §1 / §4-§10 / §12 / §13 | 人間決定領域 | ❌ 改変禁止 |
project-config.md §2 / §3 / §11 | AI 可変領域 | ⚠️ 構造のみ可(値は触らない) |
project-config.md §13 | Opus/Sonnet/Haiku tier 戦略(採点 11 で参照) | ❌ 改変禁止(参照のみ) |
.claude/CLAUDE.md | 横断ルール(原則 ⑥: ≤200 行目安) | ✅ |
.claude/skills/*/SKILL.md | スキル骨格(frontmatter / pipeline / description) | ✅ |
.claude/agents/*.md | 単発専門家定義(最小権限 / 単一責務) | ✅ |
.claude/teams/TEAM_*.md | オーケストレーション | ✅ |
.claude/hooks/*.sh | 3 層防御 Layer 1 | ❌ 本スキルでは触らない(別 PR で議論) |
.claude/rules/*.md | パス / 言語別ルール拡張 | ✅(.example 規約を維持) |
過去レポート(output/reports/harness-refine/) | adaptive ループの学習入力 | 読取のみ |
| 公式ドキュメント | 最新 best practice | WebFetch / Context7 MCP |
基本姿勢(改変境界 — MUST 守れ)
| 領域 | 可否 | 補足 |
|---|
constitution.md | ❌ | 改変は別 PR + .constitution.sha256 更新が必須(原則範囲外) |
project-config.md §1 / §4-§10 / §12 / §13 | ❌ | 人間決定領域 |
project-config.md §2 / §3 / §11 | ⚠️ | 構造的整形のみ。値の改変は禁止 |
.claude/CLAUDE.md | ✅ | 200 行を超えない(220 行ハード上限) |
.claude/{skills,agents,teams,rules,output-styles}/ | ✅ | name 衝突 / 循環参照を作らない |
.claude/hooks/*.sh | ❌ | スクリプト本体の編集は禁止(原則 ⑤) |
docs/, output/, testreport/ 内容 | ❌ | 本スキル対象外(output/reports/harness-refine/ のみ書く) |
input/requirements/ | ❌ | 人間入力 |
破ろうとした場合は 即停止して人間に確認。scan-harness.sh フックが検知する場合もある。
使い方
/harness-refine <対象ディレクトリ or 補正指示(省略可)>
引数を省略した場合は project-blueprint/ と project-blueprint-en/ 全体を対象とする。代表的な起動例:
- 「ハーネスを補正して」「ベストプラクティス準拠で再構築して」「セルフリファインして」
- 「.claude/ の構造を見直したい」「skill / agent / team の配置を点検したい」
- 「project-blueprint と project-blueprint-en の整合性を整えて」
全体ワークフロー(Round 0 + 2 ラウンド固定 — 3 ラウンド目は禁止)
Round 0(非破壊・自己強化) ラウンド 1 ラウンド 2
┌─────────────────┐ ┌─────────────┐ ┌─────────────┐
│ 公式 BP 再取得 │ │ 1-A 自己採点 │ │ 2-A 自己採点 │
│ 過去レポート学習 │ ── rubric ─→ │ (rubric) │ │ (差分中心) │
│ ルーブリック差分 │ 差分注入 └─────┬────────┘ └─────┬────────┘
└─────────────────┘ ▼ ▼
┌─────────────┐ ┌─────────────┐
│ 1-B 自己強化 │ ─ 日英ミラー適用 → │ 2-B 自己強化 │ ─ 日英ミラー →
└─────┬────────┘ └─────┬────────┘
▼ ▼
┌─────────────┐ ┌─────────────┐
│ 1-C レビュー │ (code-reviewer) │ 2-C レビュー │ (code-reviewer)
└─────┬────────┘ └─────┬────────┘
└──────► R2 入力 ───────────────┘
▼
最終レポート出力
- Round 0 で 最新ベストプラクティス取得 + 過去レポート学習(ファイルは一切編集しない)
- ラウンド 1 で 大枠補正(命名揺れ、配置ミス、frontmatter 欠落、ミラー乖離など)
- ラウンド 2 で R1 残課題 + 二次効果(
@import 切れ、CLAUDE.md スキル一覧との不整合、リンク 404)
- 各ラウンドのレビューは
pr-review-toolkit:code-reviewer agent に委任して 独立判定を取る
- ラウンド 2 で承認に届かなければ 人間にエスカレーション(自動 3 ラウンド禁止)
Round 0 — ベストプラクティス・リフレッシュ(自己強化プリフライト / 非破壊)
ファイルを 一切編集しない。調査と差分生成のみ。手順:
- 最新公式ガイダンスの取得: 末尾「ベストプラクティス基準ソース」の URL を WebFetch、
ライブラリ系は Context7 で取得する。取得失敗時は degraded モードとして訓練データ + 過去レポートで継続し、
その旨を会話とレポートに明示する(無言で訓練データに退行しない)。
- 過去レポート学習:
output/reports/harness-refine/REFINE_*.md(あれば最新 2〜3 件)を読み、
(a) 未解決課題 (b) 2 回以上再発した指摘 を抽出する。
- ライブ・ルーブリック差分の生成: 取得した最新ガイダンスを下記 15 項目 rubric と突き合わせ、
- 既存項目の判定基準が古ければ 今回ラウンドの暫定基準として更新する
- 公式に新しい強い推奨があれば 新規採点項目候補として記録する
- 再発課題は 優先補正対象へ昇格する
- 人間承認ゲート: 新規採点項目の追加提案、または
constitution.md に波及する変更は、
採用前に人間へ提示して承認を得る(自動編集禁止)。
Round 0 の出力(会話 + 最終レポートに記載):「取得ソースと取得可否」「再発課題リスト」「今回適用する rubric 差分」。
ラウンド 1 — 大枠補正
1-A. 自己採点(15 項目 × 0/1/2 点 = 30 点満点)
採点は acceptance checklist 方式(spec-kit 流): 各項目の 2 点条件を満たすかを YES/NO で判定し、根拠を添える。
A 群 — constitution / 構造の不変条件
| # | 項目 | 0 点 | 1 点 | 2 点 |
|---|
| 1 | constitution 7 原則の遵守 | 違反あり | 形式上遵守 | + scan-harness.sh でテスト化 |
| 2 | CLAUDE.md ≤200 行(原則 ⑥) | 220 行超 | 200-220 行 | 200 行以下 + 真の削減は path-scoped rules/ で実現(@import は context を減らさない点を理解) |
| 3 | skill frontmatter 規約 | name / description 欠落 | 全項目あり | + allowed-tools(最小権限)/ context / argument-hint 整備 |
| 4 | 三層分離(skill ⇄ agent ⇄ team, 原則 ④) | 循環 / 混在あり | 直線的 | + agents/README.md に選定ガイド |
| 5 | 3 層防御維持(原則 ⑤) | hook 削除あり | 同数維持 | + 各 hook の責務 header コメントあり |
| 6 | 日英ミラー同期(原則 ②) | ファイル数 / 構造に差 | ファイル数一致 | + 章立て・行数まで一致(機械 diff で乖離 0) |
| 7 | rules オプトイン方式 | .example なし or 直読み込み | .example あり | + 命名規約(language-*, path-*, rule-*)厳守 |
| 8 | 5 品質ゲート(原則 ③) | 削減あり | 5 ゲート存在 | + 各 skill から @.claude/quality-gates.md 参照 |
B 群 — Anthropic 公式ベストプラクティス + GitHub TOP5 エッセンス
| # | 項目 | 0 点 | 1 点 | 2 点 |
|---|
| 9 | pipeline 連携・発見可能性(superpowers 流) | 前後工程記載なし / dead-skill あり | 一部記載 | 全 skill に「前 → 本 → 後」表 + どの導線からも孤立した skill なし |
| 10 | 公式 best-practice 準拠 | 古い形式 | 一部準拠 | Round 0 取得の最新形式に準拠 |
| 11 | skill description 品質(三人称 / トリガー明示) | 一人称・二人称 or 曖昧 | 三人称 | + ≤1024 字 / トリガー具体的 / 重複トリガーなし |
| 12 | progressive disclosure | SKILL.md 肥大(>500 行)/ 冗長な背景説明 | ≤500 行 | + 相互排他な詳細を第 3 階層(参照ファイル)へ分割 |
| 13 | agent 最小権限・単一責務 | 読取専門 agent に Write/Edit / 多責務 | tools allowlist あり | + read-only 系は Write 無し / 1 agent=1 task / 要約のみ返す契約を明記 |
| 14 | モデル tier 配置(§13 / BMAD 流) | tier 記載なし | tier 記載あり | + 計画系=高 tier / 機械的作業=低 tier の妥当配置 |
| 15 | eval-first / 受け入れチェックリスト(spec-kit 流) | 検証観点なし | 出力契約あり | + 代表シナリオ + PASS 条件が SKILL.md に明示 |
目標(将来の項目追加でも壊れない %): ラウンド 1 で ≥80%(≥24/30)、ラウンド 2 で ≥95%(≥28/30)。
採点根拠は会話内に 必ずファイルパス + 行番号で提示する(「なんとなく低い」は禁止)。
項目 10 / 11 / 12 の判断は Round 0 で取得した最新公式ガイダンスを基準にする。
1-B. 自己強化(補正)
スコア 0 / 1 点の項目を補正する。優先順(Round 0 で昇格した再発課題を最優先):
- constitution 違反: 即停止 → 人間確認(自動修正禁止。違反内容を箇条書きで提示)
- CLAUDE.md 行数超過: トピックを
@.claude/rules/<topic>.md に切り出し → 真に context を削るなら path-scoped 化
- frontmatter 欠落 / 命名揺れ / description 品質: 三人称・トリガー明示・最小権限 allowlist に統一
- 三層分離違反: 該当呼び出しを単方向に矯正(skill → agent は可、agent → team は禁止)
- ミラー乖離: 不足側にコピーし、文言は既存
README-en.md のトーンで翻訳
.example 規約違反: 実体ファイルを .example に戻すか、命名規約に揃える
ミラー適用ルール:
- 日本語側で 1 ファイル変更したら 同じターンで英語側にも適用(片側だけで完了させない)
- 構造は完全一致、文言のみ翻訳。章立て番号・テーブル列・コードブロックは bit-identical
- 英語版にだけある体裁要素(セミコロン区切り等)は維持
1-C. セルフレビュー(独立判定)
Agent 経由で pr-review-toolkit:code-reviewer を 1 回呼ぶ。渡すコンテキスト:
- ラウンド 1 で行った全 Edit / Write の
git diff
constitution.md 7 原則の遵守チェックを明示依頼- 日英ミラー差分(
diff -r project-blueprint/.claude/skills/ project-blueprint-en/.claude/skills/ の結果)
レビュー結果(MUST / SHOULD / CONSIDER)はラウンド 2 入力に集約。
ラウンド 2 — 残課題と二次効果(adaptive)
2-A. 自己採点(差分中心 + 解消率)
ラウンド 1 で 1 点以下 だった項目を再採点。加えて以下を新規スコア対象に追加:
- ラウンド 1 Edit の副作用(
@import 切れ、参照リンク 404、CLAUDE.md スキル一覧との不整合)
- ミラー側に取りこぼした変更
- code-reviewer の指摘(MUST は必ず採点へ反映)
- 解消率トラッキング: Round 0 で抽出した再発課題が今回解消されたか(再発 3 回目以上は人間エスカレーション候補)
2-B. 自己強化(クロージング)
-
残スコアを 2 点に引き上げる微修正のみ。新規大規模変更はしない
-
@import リンク全件の存在確認:
grep -rh '^@\.claude' project-blueprint/ project-blueprint-en/ | sort -u | \
while read line; do
path="${line#@}"
test -e "project-blueprint/$path" || echo "MISSING(JP): $path"
test -e "project-blueprint-en/$path" || echo "MISSING(EN): $path"
done
-
CLAUDE.md スキル一覧表の rebuild(.claude/skills/*/SKILL.md の name: と突き合わせ)
-
ファイル数差を 0 に:
diff <(cd project-blueprint && find .claude -type f | sort) \
<(cd project-blueprint-en && find .claude -type f | sort)
2-C. セルフレビュー(最終)
再度 pr-review-toolkit:code-reviewer を呼ぶ。判定:
| レビュー判定 | 次アクション |
|---|
| 承認 | 最終レポート生成 → スキル終了 |
| 条件付き承認 | 残 MUST 修正可能か確認 → 可なら修正、不可なら人間エスカレーション |
| 要修正 | 即停止して人間エスカレーション(ラウンド 3 への自動継続は禁止) |
出力契約
最終レポート(必須)
output/reports/harness-refine/REFINE_<YYYY-MM-DD>_<HHMM>.md に出力:
# ハーネス補正レポート — <日付>
## サマリ
- ラウンド 1 スコア: NN/30(N%) → ラウンド 2 スコア: MM/30(M%)(目標 ≥95%)
- 補正ファイル数: 日本語側 X / 英語側 Y(差分 0 が MUST)
- constitution 違反: 検出 N 件 / 修正 N 件(自動修正は 0、すべて人間確認経由)
- code-reviewer 判定: 承認 / 条件付き / 要修正
## Round 0 — ベストプラクティス・リフレッシュ
- 取得ソース: [URL ごとに 取得成功 / degraded]
- 再発課題(過去レポート由来): [箇条書き / 解消率]
- 今回適用した rubric 差分: [更新した判定基準 / 新規項目提案(人間承認待ち)]
## ラウンド 1
### 採点(15 項目)
[各項目: 点数 + 根拠ファイル:行]
### 補正
[ファイルパスごとの変更要約 + WHY]
### レビュー結果
[code-reviewer agent 出力サマリ]
## ラウンド 2
[同上 + 解消率]
## 残課題
- (あれば箇条書き。人間判断が必要なもののみ)
## ミラー差分検証
- ファイル数 diff: 一致 / 差 N
- 章立て差: なし / N 件(列挙)
- `@import` 切れ: 0 件 / N 件(列挙)
会話への提示
- Round 0 開始時に「取得する公式ソースと過去レポート学習結果」を明示
- 各ラウンド開始時に「これからラウンド N の採点を行います」と明示
- 採点結果は 1 行 1 項目 で表示(箇条書き)
- 補正は 何を / なぜ / どこを を都度報告(silent edit 禁止)
- ミラー適用は JP → EN を同一ターンで報告
他スキルとの連携
| 前工程 | 本スキル | 後工程 |
|---|
| (なし — メタスキル) | /harness-refine | /code-review(コード側) / /refactoring(コード側) |
/refactoring はソースコード再構成、本スキルはハーネス骨格再構成と役割が異なる。混同しないこと。
禁止事項
constitution.md の改変(全文 immutable)project-config.md §1 / §4-§10 / §12 / §13 の改変.claude/hooks/*.sh 本体の改変(原則 ⑤)- 日英ミラーの 片側だけ更新して完了とすること(原則 ②)
--no-verify / --force を使った git 操作- 3 ラウンド以上の自動ループ(ラウンド 2 で承認得られなければ人間判断)
- Round 0 でのファイル編集(Round 0 は非破壊・調査専用)
- 新規採点項目や constitution 波及変更を 人間承認なしで自動採用すること
- ソースコード /
docs/ 内容 / output/(本スキル成果以外) / testreport/ への変更
- 採点根拠を伴わないスコア提示 / Round 0 取得失敗を無言で訓練データに退行させること
ベストプラクティス基準ソース(Round 0 で再取得 — 公式一次ソース優先)
| ソース | 用途 | rubric 対応 |
|---|
platform.claude.com/docs agent-skills/best-practices | SKILL.md / frontmatter / progressive disclosure / eval-first | 3, 11, 12, 15 |
docs.claude.com claude-code/sub-agents | subagent 最小権限・単一責務・要約返却 | 13 |
docs.claude.com claude-code/memory | CLAUDE.md 行数 / @import は context 削減せず / path-scoped rules | 2 |
anthropic.com/engineering writing-tools-for-agents | ツール定義の明確さ・トークン効率 | 10, 11 |
anthropic.com/engineering effective-context-engineering-for-ai-agents | コンテキスト curation / sub-agent 隔離 | 12, 13 |
anthropic.com/engineering effective-harnesses-for-long-running-agents | 起動オリエンテーション / 検証ループ | 9, 15 |
| GitHub: spec-kit / BMAD-METHOD / SuperClaude / agent-os / superpowers | acceptance checklist / モデル tier / standards 集約 / discoverability | 9, 14, 15 |
取得に失敗したソースは degraded として明示し、当該 rubric 項目は前回基準で暫定採点する。
関連参照(必要に応じて Claude が load)
@.claude/guardrails.md
@.claude/quality-gates.md
@.claude/rules/workflow-advanced.md
@.claude/pitfalls.md
