Pev Team Conventions

pev-team-conventions

team-conventions.md をチーム規約の Source of Truth とし、PEV pipeline が起動時に自動でpromptに注入する仕組み。dog food で「planner が team-conventions.md を自然に参照する」挙動を確認済み (v0.1, v0.2)。v0.5 はこれを明示的な protocol として整える。

When to Use

• planner / executor 起動時 (自動、毎回)
• 新しいチームメンバーが pev-harness を導入した時
• 既存プロジェクトに pev-harness を導入する時

Injection 規約 (v0.5 protocol)

読み込み優先順位

agent (planner / executor) は起動時にこの順序で規約ファイルを探す:

1. ~/.claude/pev/team-conventions.local.md (個人 override、最優先)
2. <project_root>/team-conventions.md (チーム共有)
3. なし (デフォルト動作)

<project_root> は git rev-parse --show-toplevel で決まる。git管理外なら cwd。

複数見つかった場合、両方を読み込み、local.md のセクションが project側 と被ったら local 優先。

Injection 位置

agent prompt の 冒頭、# Your task の直前に以下フォーマットで挿入:

# Team Conventions (auto-injected by pev-team-conventions skill)

<team-conventions.local.md 内容 — もしあれば>

<team-conventions.md 内容 — もしあれば>

---

# Your task
<本来の planner / executor 入力>

不在時:

# Team Conventions
(none found — operating on PEV defaults)

---

# Your task
...

Section ごとの利用先

team-conventions.md の構造化された section を、PEV pipeline 内でどこに反映するか:

Verification commands (v1.8+ 必須項目)

PEV pipeline の verifier は 4 種類の check (Unit test / E2E test / Lint / Typecheck) を実行する。 team-conventions.md には 必ず以下の項目を明示する。 「無い」場合も 未設定 と明記する (skill が探して見つからないコストを削減):

## Verification commands

- Unit test: `npm test`        (or `未設定` if none)
- E2E test:  `npx playwright test`  (or `未設定`)
- Lint:      `npx eslint .`    (or `未設定`)
- Typecheck: `tsc --noEmit`    (or `未設定`)

規約:

• 4 項目すべて記載必須 (省略不可、 「無い」場合は 未設定 を明記)
• 既存 ## Test 規約 section と統合可。 ただし上記 4 keys は必ずいずれかの場所に存在
• verifier はこの section を読んで、 未設定 の check を skip 扱いで PASS と判定する (warning なし)
• 記述なし (key 自体が missing) の場合、 verifier は推論 (file 探索 + npm run 列挙) する fallback 動作だが、 v1.8+ では template 違反として warning を出す

理由 (#19 finding): v1.7.1 dog food で verifier が npx eslint を探して見つからない → スキップ という推論を毎回行っていた。 team-conventions に「未設定」を明示すれば推論不要で短絡判定できる。

planner / executor 側の責務

各 agent は 自分で team-conventions を読む。skill の役割は「読み込み protocol を規約として固定」し、各 agent が同じ順序・同じ位置で読むよう保証すること。

具体的には:

1. agent prompt 内に ## Team conventions loading セクションを置く (planner.md / executor.md 参照)
2. agent は起動直後、上記優先順位でファイルを探して読む
3. 読み込んだ内容を Constraints / Code style / etc. に統合する
4. プロンプト出力 (plan.md, execute.log) にどの規約を適用したかを明示する (verifier や human reviewer のため)

Examples

Project でのセットアップ

# 既存プロジェクトに pev-harness を導入する時
cd <your-project>
cp ~/pev-harness/examples/team-conventions.example.md ./team-conventions.md
# → 内容をプロジェクト固有に編集
git add team-conventions.md
git commit -m "chore: add team-conventions for pev-harness"

個人 override

# 「自分のtaskでは追加で X も守りたい」のような個人ルール
cat > ~/.claude/pev/team-conventions.local.md << 'EOF'
# Personal additions to team conventions

## Forbidden (personal)
- TODO comments without an assignee
- Function bodies over 50 lines (extract helper)
EOF

dog food evidence (v0.1, v0.2 ともに確認済み)

planner が team-conventions.md の ## Language & Stack を読んで plan.md の ## Constraints に自動反映:

## Constraints
- JavaScript ESM, Node >= 20      ← team-conventions から
- Named exports only              ← team-conventions から
- 2-space indent, semicolons      ← team-conventions から
- No console.log                  ← team-conventions から
- No TypeScript migration         ← team-conventions から

v0.5 では、この自然発生していた挙動が protocol として規約化 されたので、各 agent が同じ順序で読み、同じ書式で plan.md / execute.log に反映するようになる。

メンテナンス指針

• team-conventions.md は PR レビュー対象に含める
• 規約変更時は CHANGELOG (プロジェクト側) に記録
• 過度に長くしない (1ページ以内目安)
• 「やるな」より「こうしろ」を書く (positive instruction)
• 個人 override (~/.claude/pev/team-conventions.local.md) はチーム不整合のリスクなので、長期化するなら project 側に昇格すべき

注意点

• プロジェクト固有ルールはここに集約する (skill / agent prompt にhardcodeしない)
• バイナリ的な好み (semicolon 有無等) は formatter で強制し、conventions には書かない
• secret / API key を書かない (git に入る前提)
• 個人 override は ~/.claude/pev/team-conventions.local.md 固定パス (他のパスは読まない、規約をシンプルに)
• pev-team-conventions skill 自体には team-conventions.md の中身を hard-code しない (project-agnostic を保つ)