xp-harness の skill / agent に関する作業 (新規作成 / 設計 / 改修 等) で必ず発火させる、skill 設計の流儀 (構造 / 境界原則 / description の書き方) と判断軸。
The English summary is being prepared. Showing the original description.
Review the instructions the agent will receive before you install.
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 の検証で確立):
instruction (= 常時効かせる芯) が skill を呼び、詳細を skill に委ねるのが依存の向き。逆向きはない。skill 本文は、呼び出し元の instruction に何が書かれているかを前提にしない (= skill 単体で読んで規律が揃っている状態を保つ)。
帰結として、同じ規律が instruction と skill の両方にあるのは重複ではない。層が違うので、それぞれの層で成立している正しい状態。重複を数えるときは層をまたいで数えない (= 「配布物全体で N 箇所に同じことが書かれている」という数え方は、依存の向きを見ていない)。重複として削る判断が成立するのは、同じ層の中で同じことが書かれているときだけ。
skill の frontmatter description は「9 割の skill 発火失敗は description の品質に起因」(Claude Code 公式) と言われる重要 field。以下を守る:
when_to_use frontmatter field を使う選択肢もある (Claude Code 固有)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
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、ファイル名と一致させる必要はないが明示する)name) の語形公式 docs の Naming conventions に基づく。subagent の名前は対象外 (= code-reviewer / done-verifier のように役割を表す名詞で揃っている別系統)。
processing-pdfs / analyzing-spreadsheets)。名詞句 (pdf-processing) と動詞形 (process-pdfs) も代替として明記されている。story-slicing のように後ろに -ing が来るものは、公式の分類では名詞句 (= pdf-processing と同型) なので採ってよいbasic-design / slice-tdd / define-requirements 等) はそのまま許容する。理由は改名コスト — skill 名は利用者が直接呼ぶ入口で、instruction や他 skill 本文からも名指しされており、改名は呼び出しを壊す上の字数の目安 (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 が用途別に振る舞う前提)。
改修しても、狙った振る舞いが出るかは transcript を観測しないと分からない。発火や振る舞いに効く改修をしたら、harness-verification skill を呼んで確かめる。
判断軸は「この改修で main session の振る舞いが変わることを期待しているか」。期待しているなら、確かめずに閉じない (= 期待は仮説で、まだ観測していない)。
要らないのは、typo の修正・見出しの整形・参照先パスの追随など、読み手の判断材料が変わらない改修。「言い回しを整理しただけ」は免除の理由にならない — description の文言変更は整理のつもりでも発火確率に効く (実測: 旧 3/3・新 0/3 の回帰)。文言を触ったかどうかでなく、読み手の判断材料が動いたかで切る。
呼ばないと判断したときは、その理由を依頼者に出す (= 黙って省かない)。重さを理由にするなら、確かめずに閉じることを依頼者が承知した状態にする。
skill-reviewer (手順 6) が見るのは設計の規律で、実際に発火・振る舞いが出るかは見ない。両方を通して初めて改修が閉じる。
skill / agent 改修中に依頼者と対話・議論する場面が出る。対話の規律は dialogue-principles skill に集約されている (= 省略しない / 番号で参照しない / 英語混じり禁止 / 即同意しない / 別角度から発想する / 機械的処理に流れない)。
skill 改修と対話は同時に起きるので、両方の skill を併用する: skill-design-style (= 本 skill) + dialogue-principles。
No reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
xp-harness の公開済みリリースを要約して、チーム周知用の短いテキスト (利用者向けの変化 + 更新手順) を作る。「リリースをアナウンスしたい」「この期間のリリースをまとめて周知したい」「土日の分まとめて」と言われたときに発火。投稿はせずドラフト生成に留める。
The English summary is being prepared. Showing the original description.
要件が固まった機能・変更について、アーキテクチャ・ER・シーケンス・論理設計までを対話で固める「基本設計フェーズ」のスキル。docs/working/<title>/要件定義.md が既にある状態で「設計を進めて」「basic-design」と言われたら必ず発火させる。要件定義が終わって設計フェーズに入りたい依頼、データモデルや API 設計や画面遷移の議論、コンポーネント分割や責務分離の相談、「どう作るか」の構造的な設計が必要な場面で使う。
The English summary is being prepared. Showing the original description.
新規・変更・削除・改善などの要望やレビュー指摘を受けたら、設計や実装に入る前にまず必ず発火させる「要件定義フェーズ」のスキル。依頼者のインテントを読み取り、Why / Done / スコープ / 影響範囲を引き出す。見える挙動が変わる依頼全般が対象で、やることが具体的でも md にまとめられていても発火させ、複数の要望が混ざる依頼ほど積極的に発火させる。発火しないのは、再現条件と期待動作が完全に明確なバグ修正、依存更新・タイポ修正などの定型作業、要件定義と基本設計の文書が両方揃った実装フェーズの続き（メモや TODO があるだけでは除外しない）だけ。
The English summary is being prepared. Showing the original description.
依頼者と議論・対話を進める場面で必ず発火させる skill。共創を目指して、認識を小さく揃えながら、同じ抽象度・レイヤーで話すための対話の進め方を扱う。要件・設計フェーズの対話、実装中の設計判断の議論、レビュー結果の共有、複数の論点・選択肢を依頼者に渡す場面、依頼者からの指摘・反論に応答する場面、「確認したい」「議論したい」「相談したい」と問いかけたいとき、いずれも発火対象。「会話」ではなく「対話」を成立させたい全場面で効く。質問がスルーされる・訂正が続く・話題を変えられる・「そうじゃなくて」と返されるなど、噛み合っていない兆候を観測したときは軌道修正のために再度発火させる。
The English summary is being prepared. Showing the original description.
内部由来の知見（ふりかえりの反映・実プロジェクトの検証記録など）を公開リポジトリに出す前に、組織固有の固有名詞（会社名・内部リポ名・顧客名・人物名・プロジェクト名・ID・パス等）の混入を独立点検して防ぐ。公開 git 履歴は遡れて消せないため、コミット / push の前に必ず通す。機密・認証情報の検査は扱わない。
The English summary is being prepared. Showing the original description.
E2E テストの spec を書く・編集する・レビューする際に必ず発火させる。新しいシナリオの追加、既存 E2E テストの修正・デバッグ、E2E テストの書き方の相談、slice-tdd skill から E2E spec が必要と判断された場面で使う。触る範囲に対応するプロジェクトの E2E の流儀 (spec の書き方・構造・命名) を探して従わせる入口。E2E を実行する手順は扱わない (別スキルの責務)。
The English summary is being prepared. Showing the original description.