Menu
xp-harness の skill / agent に関する作業 (新規作成 / 設計 / 改修 等) で必ず発火させる、skill 設計の流儀 (構造 / 境界原則 / description の書き方) と判断軸。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
xp-harness の skill / subagent が意図どおり振る舞えているか (発火するか・あるべき振る舞いができているか) を transcript で事実確認する手順。skill / subagent を改修した後に sandbox で動作検証したいとき、または本番の実運用セッションを「あるべき振る舞い」に照らして分析したいとき、「検証したい」「発火するか確かめたい」「このセッションを分析したい」と言われたときに発火させる。核は発火・振る舞いができたかの事実確認で、本番セッションでは自走の良し悪し (止まり方・判断の質など) も見る。
要件が固まった機能・変更について、アーキテクチャ・ER・シーケンス・論理設計までを対話で固める「基本設計フェーズ」のスキル。docs/working/<title>/要件定義.md が既にある状態で「設計を進めて」「basic-design」と言われたら必ず発火させる。要件定義が終わって設計フェーズに入りたい依頼、データモデルや API 設計や画面遷移の議論、コンポーネント分割や責務分離の相談、「どう作るか」の構造的な設計が必要な場面で使う。
新規・変更・削除・改善などの要望やレビュー指摘を受けたら、設計や実装に入る前にまず必ず発火させる「要件定義フェーズ」のスキル。依頼者のインテントを読み取り、Why / Done / スコープ / 影響範囲を引き出す。見える挙動が変わる依頼全般が対象で、やることが具体的でも md にまとめられていても発火させ、複数の要望が混ざる依頼ほど積極的に発火させる。発火しないのは、再現条件と期待動作が完全に明確なバグ修正、依存更新・タイポ修正などの定型作業、要件定義と基本設計の文書が両方揃った実装フェーズの続き（メモや TODO があるだけでは除外しない）だけ。
依頼者と議論・対話を進める場面で必ず発火させる skill。共創を目指して、認識を小さく揃えながら、同じ抽象度・レイヤーで話すための対話の進め方を扱う。要件・設計フェーズの対話、実装中の設計判断の議論、レビュー結果の共有、複数の論点・選択肢を依頼者に渡す場面、依頼者からの指摘・反論に応答する場面、「確認したい」「議論したい」「相談したい」と問いかけたいとき、いずれも発火対象。「会話」ではなく「対話」を成立させたい全場面で効く。
Git 運用の規律 (branch / worktree 運用、commit / push / pull / rebase / conflict 解決、remote 同期、完了時の統合) を一元的に担う skill。コード変更を伴う依頼・セッション開始・Git 操作の話題のいずれかに該当したら、他より先に必ず最初に使う。ファイルを 1 行でも書き換える依頼なら Git に無関係に見えても発火し、セッション開始・作業再開 (「前回の続き」「何から始めよう」等) でも必ず発火する。発火しないのはコードを読むだけの質問、Git の概念学習質問、doc のサマリ依頼。project 固有ルールでの部分上書きに対応する。
設計判断・ライブラリ選定・アーキ判断・実装アプローチが 2 つ以上ありえる場面で必ず発火させる、「複数案＋メリデメ＋推奨」を提示する横断スキル。「どっちがいい？」「これでいい？」「方針を相談したい」と聞かれたとき、ライブラリ選定・ディレクトリ構成・API 設計・テスト戦略のように選択肢が複数ある相談を受けたとき、要件定義 / 設計 / 実装の中で「複数アプローチがありそう」と感じたときに必ず使う。一案だけポンと出さない。
| name | skill-design-style |
| description | xp-harness の skill / agent に関する作業 (新規作成 / 設計 / 改修 等) で必ず発火させる、skill 設計の流儀 (構造 / 境界原則 / description の書き方) と判断軸。 |
xp-harness の harness 機構 (= skill / agent / CLAUDE.md) を改修者が改修するとき、規律 / 判断軸 / 改修フローが散在していると、改修者 (main session) が機械的処理に流れて失敗する。本 skill は改修者向けの規律 / 判断軸 / 改修フローを単一の出典 (= single source) として集約する。
改修者が「やりたいこと」を伝えたら、main session (コーディング Agent) が harness 機構に適切に落とし込めるよう、ある程度自走して任せられる状態を実現する。本 skill はその自走を支える規律集。
「依頼者から都度説明を受けないと整理できない」状態を解消し、.apm/ 配下 (= 利用者向け本題) の改修を進められる状態にする。
skill / CLAUDE.md / subagent の harness 機構には E2E テスト枠組みが未確立。改修の Done は事前縛りを最小化し、事後評価を許容する。投資フェーズの仕組み作りでは、運用コスト最適化より価値命題の充実を優先する。
reviewer 系の subagent (code-reviewer / e2e-reviewer / pre-implementation-reviewer / done-verifier / skill-reviewer) は、強制 gate ではなくペアプロの相手としての第三者:
xp-harness は OSS として skill / agent / instruction を配布する harness。改修対象が「利用者向け」か「改修者向け」かを必ず判別する。
| カテゴリ | パス | 配布 | 改修方針 |
|---|---|---|---|
| 利用者向け | .apm/skills/* / .apm/agents/* / .apm/instructions/* および .claude/ 配下の対応 symlink (= .apm/ と同じ実体) | APM 経由で配布 | 慎重に、scope 外なら触らない |
| 改修者向け | CLAUDE.md (project root) / .claude/skills/philosophy/ / .claude/skills/release/ / .claude/skills/skill-design-style/ / .claude/agents/skill-reviewer.md (それぞれ git tracked、symlink でない) | 非配布 | philosophy skill と同じパターン、.claude/ 配下に直接コミット |
判別法: ls -la で symlink でないことを確認。symlink なら .apm/ 配下と同じものなので利用者向け、symlink でなく直接コミットされていれば改修者向け。
新規 skill / agent を改修者向けで作るときは、必ず .claude/ 配下に直接コミット (= .apm/ には置かない)。
skill / agent を新規作成・改修するときは、以下の手順を順に通す。
skill / description / 本文 / 要件定義.md / 他 skill / CLAUDE.md のどこに書くべきか、以下 4 軸で位置づける:
docs/working/<title>/要件定義.md, 基本設計.md4 軸で位置づけてから書く。一つでも答えに詰まったら、書く場所を再考する。
これは 4 軸の 3 番目 (= 既出か / 源泉に集約するか) を、個別案件をまたぐ時間軸に広げた運用。個別案件 (docs/working/<title>/ の要件定義・基本設計) の中で、xp-harness の責務境界・採否に関わる新しい原則を言語化したら、その案件の文書に埋もれさせず、思想・判断軸の源泉である philosophy skill の該当 section に昇格させる。
理由: philosophy は CLAUDE.md 経由で常時 context に乗る源泉。個別案件の文書は次の判断のとき読まれない。源泉に昇格させないと、同じ原則を毎回その場で組み立て直し、判断の向きを外す (= 実際に「規約探索型スキルへの薄型化」案件で、決定打の境界原則が要件定義.md にしか無く philosophy に無かったため、main session が責務境界を超える判断を繰り返した)。
skill / agent は 2 層構造:
name / description / その他 metadata。常時 context に乗り、main session が「この skill を呼ぶか」を判断するための signal。抽象表現で書くskill 全体は「interface + 実装」のセット。「skill = description」「skill = 本文」のいずれかと同視するのは取り違え。
「呼ばれる前」と「呼ばれた後」を区別する: 起動 / 判断 / 提案 は呼ばれる前 (= description が効く)、発火 / 振る舞い / 完了 は呼ばれた後 (= 本文が効く)。
上の 2 層構造・動作フローは skill の話。subagent (.apm/agents/* / .claude/agents/*) は 本文を読む主体が別 で、ここが skill と決定的に違う:
ここから 3 つ導かれる:
skill / agent を作る・改修するときの境界原則。
description は interface — 具体の話 / 内部情報を入れないPlaywright, Cypress)、API 名 (getByRole, test.use, page.locator)、ツール名 (gh, gh cli 等).claude/skills/ 等に deploy された状態) でも自然に読めること.apm/ / apm compile / consumer といった APM 機構の語彙はもはや関係なくなる.apm/instructions/<x>.md, apm compile, "consumer の自前 instruction", "last-installed-wins 機構" のような APM 機構固有の言及を skill 本文に直書きすること.apm/instructions/) に書く。skill 本文は APM 非依存の汎用表現で書くdescription を main session が読み、文脈にマッチしたら skill 本文が読み込まれる。発火を決めるのは description であって、本文ではないskill 本文から別の skill を使わせるときの 2 点 (実装 / E2E実行 skill の検証で確立):
skill の frontmatter description は「9 割の skill 発火失敗は description の品質に起因」(Claude Code 公式) と言われる重要 field。以下を守る:
when_to_use frontmatter field を使う選択肢もある (Claude Code 固有)name フィールドの扱い (= 公式 docs に基づく):
.apm/skills/<dir>/SKILL.md / .claude/skills/<dir>/SKILL.md、配布・改修者向けを問わず): name を 明示する (= ディレクトリ名と一致させる)。直接の理由は cross-agent 配布先 (Codex 等) が SKILL.md の name を必須とし、無いと skill がロードされないこと (ディレクトリ名へのフォールバックが無い)。Claude Code 単体なら省略してもディレクトリ名がデフォルトになるが、配布されない改修者向け skill も含めて全 skill で揃える — 有無が揃っている方がルールが単純で (「skill は name = ディレクトリ名」の一本)、「なぜこれだけ付いていないのか」の迷いや視覚的な不整合を生まない (一貫性 > 重複回避)。ディレクトリを改名するときは name も追随させる.apm/agents/<file>.md / .claude/agents/<file>.md): name は 必須 (= 公式 docs で required、ファイル名と一致させる必要はないが明示する)Good 例:
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data.
Bad 例:
description: Use openpyxl to process spreadsheets
参考: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
上の字数の目安 (200-300 字) は skill の話。subagent の description には公式の長さ推奨が無い (公式は「Claude が委譲を判断するのに使うので、いつ使うか分かる明確な description を書け」だけ)。だから subagent は字数で機械的に削らず、「呼ぶ側が 委譲判断 と 正しい呼び方 に必要な情報が揃っているか」で判断する。呼び出し規約 (何を渡す / 渡さないか) を字数のために削って呼ぶ側に届かなくするのは本末転倒 (= 手順 2 の「subagent は本文の読み手が違う」の帰結)。
参考: https://code.claude.com/docs/en/sub-agents
skill / description / 本文 / 要件 → description の変換などを書くとき、出力前に必ず立ち止まる:
「これはルーチン作業」「決まったパターンの繰り返し」と分類した瞬間に立ち止まる。具体的な自己観察項目 (= 省略しない / 英語混じり禁止 / 即同意しない / 別角度から発想する / 機械的処理に流れない の 5 項目) は dialogue-principles skill 本文の「出力の規律」section に集約されている。
skill 改修中も対話と同じ規律が効くので、dialogue-principles を必ず参照する (= 重複させない、single source として dialogue-principles を読む)。
skill / agent の改修が一段落したら、必ず skill-reviewer を呼ぶ (= 改修フローの最後の step として規律化、呼び忘れない)。skill-reviewer は本 skill (skill-design-style) を preload skill として context に注入された状態で動き、改修内容を規律に照らしてレビューする。
出力フォーマットは日本語の文章 (= severity スコアなし、対応必要性は文章の文脈で伝える)。
skill 設計 / 改修フェーズ中に skill-reviewer を呼ぶタイミングは 3 用途。手順 6 (= 改修後の最終レビュー、必須) に加えて、設計中も任意で呼べる:
必須の 1 回に加えて追加で呼ぶかどうかは main session の判断で、依頼者の許可を取る事項ではない: 変更が一段落するたび・迷うたびに気軽に呼ぶ。「skill-reviewer に通しますか？」と依頼者に委ねない (= 気軽に呼ぶは判断委任であって許可取りではない)。subagent 起動のコストや「今日もう 1 回やった」を理由に呼ぶ回数を出し惜しみしない ── code-reviewer を Refactor 前に何度でも反射的に呼ぶのと同じ気軽さで呼ぶ (捕捉の価値 > 呼ぶコスト)。
呼ばれたときの skill-reviewer の振る舞い詳細 (= 各用途で何をするか) は skill-reviewer 本文の「3 用途の使い分け」section を参照 (= subagent 自身の context、main session は直接読まないが、skill-reviewer が用途別に振る舞う前提)。
skill / agent 改修中に依頼者と対話・議論する場面が出る。対話の規律は dialogue-principles skill に集約されている (= 省略しない / 番号で参照しない / 英語混じり禁止 / 即同意しない / 別角度から発想する / 機械的処理に流れない)。
skill 改修と対話は同時に起きるので、両方の skill を併用する: skill-design-style (= 本 skill) + dialogue-principles。