메뉴
xp-harness の skill / agent に関する作業 (新規作成 / 設計 / 改修 等) で必ず発火させる、skill 設計の流儀 (構造 / 境界原則 / description の書き方) と判断軸。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
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。