idd
- Repo stars 0
- Author repo claude-skills
- Domain
- Other
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @yukkie · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- Python
- Detected file/system behavior
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# Issue Driven Development (IDD)
このスキルは AgentVillage プロジェクトの開発フローをガイドする。
## サブコマンド: `idd create`
引数が `create` で始まる場合はこのフローへ進む。残りの引数(あれば)は要求の最初のヒントとして扱う。
### 目的
対話ベースで要求を深掘りし、仕様として十分に整理された GitHub Issue を作成する。
Issue には「何を・なぜ・受け入れ条件」を記載する。実装方針は不要(それは後の Phase 4 で決める)。
### フロー
```
[C-1] ヒアリング(対話で要求を整理)
[C-2] Issue ドラフト提示 ← 確認
[C-3] Issue 作成 + Ideas.md 追記
```
#### C-1 ヒアリング
ユーザーの入力から以下の3点が揃っているか確認し、足りない点だけ追加で質問する:
1. **何を** — 追加/変更したい機能・動作の概要
2. **なぜ** — 背景・動機・解決したい問題
3. **受け入れ条件** — 「これができたら完了」と言える具体的な状態
既に書いてくれている内容は再度聞かない。3点が揃ったら C-2 へ進む。
#### C-2 Issue ドラフト提示
以下のフォーマットで提示し、確認を取る:
```
## Issue ドラフト
**タイトル**: {簡潔な英語タイトル(50文字以内)}
**本文**:
---
## Background
{なぜ必要か}
## Requirements
{何を実現するか(箇条書き)}
## Acceptance Criteria
- [ ] {完了条件1}
- [ ] {完了条件2}
---
**ラベル**: {enhancement / tech-debt / bug から該当するもの}
このIssueを作成してよいですか? [y/N / 修正コメント]
```
修正コメントがあればドラフトを更新して再提示する。
#### C-3 Issue 作成
承認後:
```bash
gh issue create \
--title "{タイトル}" \
--body "..." \
--label "{ラベル}" \
--repo yukkie/AgentVillage
```
作成後、`doc/Ideas.md` のリスト先頭に `❌` マークで追記する。
`docs/add-issue-{番号}-to-ideas` ブランチを作成してコミットし、PR を作成する。
> **⚠️ 注意**: Ideas.md 追記の PR 本文・コミットメッセージには `Closes #XX` / `Fixes #XX` を**絶対に書かない**。
> GitHub がマージ時に Issue を自動クローズしてしまうため。`Related to #XX` も不要。Issue 番号への言及は一切しないこと。
Issue番号を表示して完了。続けてそのIssueに取り組むか確認する:
```
Issue #{番号} を作成しました。
続けてこのIssueの実装に取り組みますか? [y/N]
```
`y` の場合は Phase 2(ブランチ作成)へ進む。
---
## サブコマンド: `idd import <file>`
引数が `import` で始まる場合はこのフローへ進む。続く引数はインポートするファイルパス。
### 目的
チャットやメモで整理した生の Markdown ファイルを読み込み、`doc/Ideas.md` に統合する。
GitHub Issue は作成しない — "アイデアを整理する" フェーズ専用。
### フロー
```
[I-1] ファイル読み込み + Ideas.md の現状確認
[I-2] 整形ドラフト提示 ← 確認
[I-3] Ideas.md に書き込み
```
#### I-1 読み込み
入力ファイルと `doc/Ideas.md`(存在する場合)を読む。
- **Ideas.md が存在しない**: 新規作成モード
- **Ideas.md が存在する**: 追記モード(重複するアイデアはスキップ)
#### I-2 整形ドラフト提示
入力内容をクラスタリングして以下のカテゴリに振り分ける:
| カテゴリ | 説明 |
|---|---|
| コア機能 | ゲームの根幹に関わる機能 |
| 拡張機能 | あると良い追加機能 |
| 技術的負債 / 改善 | リファクタリング・設計改善 |
| 保留 / 未検討 | まだ判断できないもの |
ドラフトを提示して確認を取る:
```
## import ドラフト
### 新規追加({N}件)
{カテゴリごとに箇条書き}
### スキップ(重複 {M}件)
{重複と判断した理由を簡潔に}
このまま doc/Ideas.md に書き込みますか? [y/N / 修正コメント]
```
修正コメントがあれば振り分けを更新して再提示する。
#### I-3 書き込み
承認後、`doc/Ideas.md` を更新する。
- 新規作成モード: ファイルを新規作成して書き込む
- 追記モード: 既存の各セクションに追記する(既存の内容は変更しない)
完了後:
```
{N}件のアイデアを doc/Ideas.md に追加しました。
続けて GitHub Issue を作成しますか? [y/N]
```
`y` の場合は `idd create` フローへ進む。
---
## サブコマンド: `idd revise <番号>`
引数の先頭語が `revise` の場合はこのフローへ進む。続く引数は対象 Issue の番号。
### 目的
Issue 作成時点から状況が変わっているケース(別 Issue の実装で AC が既に満たされた・要件がユーザーの実際の意図と乖離した・関連 Issue のコメントに調査メモが蓄積した)を検知し、**Issue 本文を現状に合わせて最新化する**。
このサブコマンドは **Issue の整備専用**。照合 → Issue 更新 →(必要なら)Ideas.md 同期までで完結し、**実装フロー(Phase 2 以降)には進まない**。実装に入りたい場合は revise 後に改めて `/idd {番号}` を実行する。
> **注意**: 明示的に `idd revise {番号}` と呼ばれたときのみ起動する。通常の `/idd {番号}`(番号のみ)では revise ステップは実行されない。
### フロー
```
[V-1] 照合(本文・全コメント・関連 Issue・memory・最近クローズ Issue を読む)
[V-2] 乖離レポート + revise 案提示 ← 確認(自動編集しない)
[V-3] Issue 更新 +(必要なら)Ideas.md 同期
```
#### V-1 照合
Phase 3 の「事前調査(関連の全数洗い出し)」と同じ要領で、以下を読んで現状と Issue 本文の差分を洗う(手順詳細は Phase 3 を参照、ここでは重複させない):
- 対象 Issue の本文 + **全コメント**(`gh issue view {番号} --json body,comments --repo yukkie/AgentVillage`)
- 本文・コメント中の `#NN` 言及から関連 Issue を引く
- `memory/MEMORY.md` と関連 memory
- 関連キーワードで**最近クローズされた Issue**(`gh issue list --search "{キーワード} is:closed" --repo yukkie/AgentVillage`)
#### V-2 乖離レポート + revise 案提示
照合結果を以下のフォーマットで提示する。**この時点では Issue を編集しない**:
```
## idd revise: Issue #{番号} 照合結果
### 現状と乖離している箇所
- {要件X}: {何がどう変わったか・根拠(別 Issue #NN / コメント / memory)}
### 既に解決済みの AC
- [x] {AC}: {#NN で充足済み}
### 意図と異なる要件
- {要件Y}: {乖離内容}
### revise 案(更新後の本文)
---
## Background
...
## Requirements
...
## Acceptance Criteria
- [ ] ...
---
この内容で Issue を更新しますか? [y/N / 修正コメント]
```
修正コメントがあれば案を更新して再提示する。
**乖離が見つからなければ**「現状と一致しています。更新は不要です」と報告して終了する。
#### V-3 Issue 更新 +(必要なら)Ideas.md 同期
承認後、Issue 本文を更新する:
```bash
gh issue edit {番号} --body "..." --repo yukkie/AgentVillage
```
続けて `doc/Ideas.md` を確認する。当該 Issue の行があり、revise でタイトル・要約が変わった場合のみ同期する(変化がなければ何もしない)。同期する場合は master 直 push 禁止のため `docs/revise-issue-{番号}` ブランチを作成してコミット・PR を作成する:
```bash
git checkout -b docs/revise-issue-{番号}
git add doc/Ideas.md
git commit -m "docs: sync issue #{番号} summary in Ideas.md after revise"
git push -u origin docs/revise-issue-{番号}
gh pr create --title "docs: sync issue #{番号} in Ideas.md" --body "..." --base master
```
> Ideas.md 同期 PR の本文・コミットには `Closes #XX` を**書かない**(自動クローズ防止)。
更新内容を表示して完了。**ここで終了する**(実装フローには進まない)。
---
## プロジェクト規律ファイル: `doc/project-discipline.md`
`idd refine` が参照するプロジェクト固有の価値観・優先度方針ファイル。
リポジトリに置くことでプロジェクトと一緒に管理・バージョン管理できる。
### ファイル形式
```markdown
# Project Discipline
## Sprint Goal
<!-- 現在のゴール。idd refine 実行時に更新する -->
ゴール: {例: ゲームが1ラウンド最後まで回ること}
## 優先度の価値観
<!-- 相対的な優先度判断の軸。考え方が変わったときだけ更新する -->
- リファクタリング vs 新機能: {例: 新機能優先 / バランス / リファクタリング優先}
- tech-debt の姿勢: {例: 積極的に返す / 詰まったら返す / 後回し}
- 安定性 vs 速度: {例: 安定性重視 / スピード重視 / バランス}
- その他: {プロジェクト固有の判断軸があれば}
```
---
## サブコマンド: `idd refine`
引数が `refine` の場合はこのフローへ進む。
### 目的
定期的なバックログ整理セッション。以下の2つをまとめて行う:
1. **昇格レビュー** — Ideas.md の未実装アイデアを GitHub Issue に昇格できるか判断する
2. **優先度メンテ** — 既存 Issue のバックログを整理し、優先度ラベルを最新化する
Issue は作成/更新の直前に必ず確認を取る。
### フロー
```
[R-0] project-discipline.md の確認・更新
[R-SP] Story Point 見積もり ← 確認
[R-1] Ideas.md 昇格候補レビュー ← 確認
[R-2] 選択候補を Issue 化(必要に応じてヒアリング)
[R-3] Issue バックログ優先度サジェスト ← 確認
[R-4] 優先度ラベル更新
[R-4b] Ideas.md 優先度同期・並び替え
```
#### R-0 project-discipline.md の確認・更新
`doc/project-discipline.md` が存在するか確認する。
**存在しない場合 — 初回インタビュー**:
以下をヒアリングし、ファイルを新規作成する:
```
project-discipline.md がまだありません。優先度サジェストのために数点確認します。
1. 今の Sprint Goal を一言で教えてください
(例: ゲームが1ラウンド回る、デモ準備 など)
2. リファクタリングと新機能、どちらを優先しますか?
(例: 新機能優先 / バランス / リファクタリング優先)
3. tech-debt はどう扱いますか?
(例: 積極的に返す / 詰まったら返す / 後回し)
4. 他に判断軸があれば教えてください(スキップ可)
```
回答をまとめてファイル内容を提示し、承認後に `doc/project-discipline.md` を作成する。
**存在する場合 — Sprint Goal の確認のみ**:
ファイルを読み込み、Sprint Goal だけ更新が必要か確認する:
```
現在の Sprint Goal: {記載されているゴール}
今もこのままですか?変わっていれば教えてください。[Enter でそのまま続行]
```
変更があればファイルを更新してから次へ進む。
#### R-SP Story Point 見積もり
オープンな Issue 一覧を取得し、`sp:X` ラベルが付いていない Issue に SP を見積もって提示する。
**SP スケール(フィボナッチ)**:
| SP | 目安工数 | 例 |
|---|---|---|
| 1 | 数時間 | 定数の置き換え、小さなリネーム |
| 2 | 半日〜1日 | 単一クラスのリファクタリング |
| 3 | 1〜2日 | 複数ファイルにまたがる中規模変更 |
| 5 | 3〜5日 | モジュール分割・新機能の骨格実装 |
| 8 | 1〜2週間 | 大規模リファクタリング・機能追加 |
| 13 | 2週間以上 | アーキテクチャ変更・大型新機能 |
**ラベル形式**: `sp:1` / `sp:2` / `sp:3` / `sp:5` / `sp:8` / `sp:13`
表示フォーマット(SP未設定 Issue のみ対象):
```
## Story Point 見積もり
| # | タイトル | 提案SP | 根拠 |
|---|---|---|---|
| 71 | Eliminate redundant role: str from ActorState | sp:2 | 単一クラスの変更、影響範囲は限定的 |
| 58 | Split GameEngine phases into dedicated modules | sp:8 | 複数モジュールへの分割、テスト影響大 |
| 21 | Day 2+ pre-night judgment phase | sp:5 | 新フェーズの追加、複数ファイル変更 |
変更を適用しますか?個別に修正する場合は番号=SP で指定してください。
例: "そのまま" / "58=5" / "skip"
```
`skip` の場合は R-1 へ。
承認後:
```bash
gh issue edit {番号} --add-label "sp:{値}" --repo yukkie/AgentVillage
```
全 Issue の処理が終わったら R-1 へ進む。
#### R-1 昇格候補レビュー
`doc/Ideas.md` を読み、`❌`(未実装)アイテムを列挙する。
各アイテムについて「受け入れ条件が書けそうか」で昇格準備度を判定する:
```
## Ideas.md 昇格候補レビュー
| # | アイデア | 判定 | 理由 |
|---|---|---|---|
| - | エージェントの感情モデル | ✅ 昇格可能 | 要件が明確 |
| - | BGM・SE の追加 | ⚠️ 要詳細化 | スコープ不明 |
| - | リプレイ機能 | ✅ 昇格可能 | 独立した機能として切り出せる |
Issue 化したいアイデアを選んでください(番号をカンマ区切り、または "skip"):
(⚠️ のものも選択可。足りない情報はその場でヒアリングします)
```
`skip` の場合は R-3 へ。
#### R-2 選択候補を Issue 化
選択された各アイデアを1件ずつ処理する。
**✅ 昇格可能な場合**: Ideas.md の内容を元に Issue ドラフトを自動生成して提示する。
**⚠️ 要詳細化の場合**: `idd create` の C-1 と同様に、不足している情報だけヒアリングする。
- 何が不明かを明示してから質問する(例:「スコープが不明です。どの画面/フェーズが対象ですか?」)
- 3点(何を・なぜ・受け入れ条件)が揃ったら Issue ドラフトを生成する
いずれの場合もドラフトのフォーマットは `idd create` の C-2 と同じ(Background / Requirements / Acceptance Criteria)。
承認後に `gh issue create` で作成する。
#### R-3 Issue バックログ優先度サジェスト
オープンな Issue 一覧を取得する:
```bash
gh issue list --repo yukkie/AgentVillage --state open --json number,title,labels,body
```
`doc/project-discipline.md` の Sprint Goal・価値観と Issue 間の依存関係・工数感を踏まえて優先度をサジェストする。
また、エラーハンドリング・エッジケース・レアケースの Issue については、以下を確認する:
- 「実運用での再現が難しいか」を判断する
- 難しい場合、Issue 本文の Acceptance Criteria に `⚠️unit test mandatory` が記載されているかチェックする
- 記載がなければ、優先度更新と同時に Issue 本文に追記する(`gh issue edit --body`)
```
## Issue バックログ 優先度サジェスト
Sprint Goal「{ゴール}」・価値観「{リファクタリング vs 新機能}」をもとにサジェストします。
| # | タイトル | 現在 | サジェスト | 理由 |
|---|---|---|---|---|
| 21 | Day 2+ pre-night judgment phase | (なし) | 🔴 high | Sprint Goal に直結するコア機能 |
| 38 | GameState dataclass導入 | 🟡 medium | 🟡 medium | tech-debt、後回し方針と一致 |
| 42 | エージェント感情モデル | (なし) | 🟢 low | 今の Goal では不要な拡張機能 |
変更を適用しますか?個別に修正する場合は番号と優先度を指定してください。
例: "そのまま" / "21=medium" / "skip"
```
**優先度ラベルの種類**: `priority:high` / `priority:medium` / `priority:low`
#### R-4 優先度ラベル更新
確定した変更内容を確認してから実行:
```
以下のラベルを更新します:
- Issue #21: (なし) → high
- Issue #42: (なし) → low
続けてよいですか? [y/N]
```
承認後:
```bash
gh issue edit {番号} --add-label "priority:{値}" --remove-label "priority:{旧値}" --repo yukkie/AgentVillage
```
完了後にサマリーを表示する。
#### R-4b Ideas.md 優先度同期
優先度ラベル更新後、`doc/Ideas.md` の優先度表記を GitHub ラベルに合わせて同期する。
- 絵文字マッピング: `priority:high` → 🔴 / `priority:medium` → 🟡 / `priority:low` → 🟢
- 優先度順(🔴 → 🟡 → 🟢)に行を並び替える
- 同一優先度内の順序は変更しない
#### R-5 コミット & PR 作成
`doc/Ideas.md` や `doc/project-discipline.md` に変更があった場合、以下の手順でコミット・PR を作成する。
**ブランチ名の形式**:
```
docs/backlog-refinement-#{セッション番号}
```
- セッション番号は 1 から始め、毎回の `idd refine` 実行で +1 する
- 現在のセッション番号は `git branch -a | grep backlog-refinement` で確認する
**手順**:
```bash
git checkout -b "docs/backlog-refinement-#{N}"
git add doc/Ideas.md doc/project-discipline.md
git commit -m "docs: backlog refinement #{N} — {変更内容の要約}"
git push -u origin "docs/backlog-refinement-#{N}"
gh pr create --title "docs: backlog refinement #{N}" --body "..." --base master
```
PR 作成後に URL を表示して終了。
---
## 通常フロー
Issue選択 → ブランチ作成 → ドキュメント確認 → 設計承認 → ドキュメント更新 → 実装 → PR作成 の順に進み、**フェーズが変わるたびにユーザーの確認を取る**。
## フェーズ概要
```
[1] Issue 選択
[2] ブランチ作成 ← 確認
[3] ドキュメント確認(読む)
[4] 設計検討 → スメル発見で 4.5 へ中断、なければ設計提示 → 承認後に任意で外部レビュー ← 確認
[4.5] コードスメル対話 ← 決着まで対話ループ → 4 に戻る
[5] ドキュメント更新(書く)
[6] 実装 + テスト
[7] PR 作成 ← 確認
[8] 教訓の振り返り(任意・pull 型) ← PR 後の区切りで一度だけ。y/N
[*] スコープ拡張ゲート(横断) ← 任意フェーズで発火。ユーザー追加指摘 / PR レビュー指摘で当初 AC 外の要求が来たとき
```
---
## Phase 1 — Issue 選択
### 番号が指定された場合(例: `/idd 42`)
そのまま Phase 2 へ進む。
### 番号が指定されていない場合
`doc/Ideas.md` を読み込み、未実装 Issue の一覧を表示する。
表示フォーマット:
```
## 取り組む Issue を選んでください
| # | 優先度 | ラベル | タイトル | 内容 |
|---|---|---|---|---|
| 37 | 🟡 | tech-debt | `build_system_prompt` のパラメータ過多 | パラメータを整理してシンプルに |
| 21 | (なし) | enhancement | Day 2+ pre-night judgment phase | 昼開始前の判断フェーズを Day 2+ にも拡張 |
...
番号を入力してください(例: 42):
```
tech-debt は表の先頭に並べる(同一優先度内でも tech-debt を上位に表示する)。
ユーザーが番号を入力するまで待つ。
> **注意**: Ideas.md に載っている Issue が GitHub 上ですでに CLOSED になっている場合は、一覧表示後に「#XX は GitHub 上でクローズ済みです。Ideas.md から削除しますか?」と確認し、承認されたら `docs/cleanup-ideas` ブランチを作成して削除・コミットし、PR を作成する。
---
## Phase 2 — ブランチ作成
### ブランチ名の決め方
Issue のラベルに応じてプレフィックスを使い分ける:
| ラベル | プレフィックス |
|---|---|
| `enhancement` / その他 | `feature/` |
| `bug` | `bugfix/` |
| `tech-debt` | `refactor/` |
形式: `{prefix}issue-{番号}-{Issue タイトルを kebab-case に変換した短縮形}`
例:
- Issue #37「`build_system_prompt` のパラメータ過多」(tech-debt)→ `refactor/issue-37-build-system-prompt-params`
- Issue #24「Role class refactoring」(enhancement)→ `feature/issue-24-role-class-refactoring`
タイトルが長い場合は 4〜5 単語に収める。
### ブランチ作成手順
#### オープン PR チェック(必須)
ブランチ作成前に、マージされていない PR が存在するか確認する:
```bash
gh pr list --repo yukkie/AgentVillage --state open --json number,title,headRefName,baseRefName
```
オープン PR が1件以上ある場合は、以下を表示して警告する:
```
⚠️ マージされていない PR があります:
| # | タイトル | ブランチ |
|---|---|---|
| {番号} | {タイトル} | {headRefName} → {baseRefName} |
...
これらが今回の実装と関連している場合、先にマージしておかないとコンフリクトが発生する可能性があります。
続けてブランチを作成しますか? [y/N]
```
`N` の場合は処理を中断する。`y` の場合は次の手順へ進む。
#### 現在のブランチが `master` の場合
確認なしで以下を実行する:
```bash
git pull --rebase origin master
git checkout -b {prefix}issue-{番号}-{名前}
```
#### 現在のブランチが `master` 以外の場合
以下を提示してユーザーに確認する:
```
現在のブランチ: {現在のブランチ}
作業ブランチを作成するには master ベースが必要です。
master に切り替えて pull しますか? [y/N]
```
承認後:
```bash
git checkout master
git pull --rebase origin master
git checkout -b {prefix}issue-{番号}-{名前}
```
拒否された場合は処理を中断し、ユーザーに手動で master へ切り替えるよう案内する。
---
## Phase 3〜6 — 実装対象による分岐
### 事前調査(設計 Issue・横断的変更では必須)
Issue が **設計 Issue(doc 更新・スキーマ定義)** または **横断的変更(ログ/イベントフォーマット・共通データ型・複数モジュールにまたがる契約変更)** の場合、Phase 3 に入る前に以下を**必ず**実施してから設計を組む。これを飛ばすと「見落とし → 設計やり直し」になりやすい(実例: #344 で wolf_chat の同種ハック・CLI renderer の consumer・co_announcement の二重化を初回に拾えなかった)。
1. **関連の全数洗い出し** — 対象 Issue の**全コメント**を読む(`gh issue view N --json comments`)。本文・コメント中の `依存:` / `#NN` 言及をたどって関連 Issue を引く。`memory/MEMORY.md` と関連 memory を確認する。同種キーワードで既存 Issue を検索する(`gh issue list --search`)。
2. **同種ハック/回避策の全数探索** — 回避策(プレフィックス・別イベント emit・フラグ分岐等)を1つ見つけたら、「同じ回避策が他の経路にもないか」を grep で網羅する。1箇所直して他を残すと中途半端になる。
3. **producer / consumer の全列挙** — スキーマ・フォーマットを変える場合、それを **emit する側(producer)** と **読む側(consumer)** を機械的に全部挙げる。consumer は CLI renderer・JS parser・replay・テストなど複数言語にまたがることが多い(CLI renderer の見落としに注意)。`LogEvent` / `EventType` / `spectator_log.jsonl` / エージェント JSON のデータ契約は `doc/DataSpec.md` が SSOT。EventType 一覧・可視性ルール・スキーマはまずここを参照し、変更時は `doc/DataSpec.md` も併せて更新する。
- **⚠️ grep が届かない境界に注意** — consumer の中には**プロジェクト外(別リポジトリ)にあるもの**が存在する。とくに idd スキル定義(`~/.claude/skills/idd/` 配下の `SKILL.md` / `references/flow-*.md`)はプロジェクトの doc・データ契約を参照しているが、`d:\git\AgentVillage` を grep しても出てこない。**doc・データ契約・データスキーマを変更/新設するときは、スキル定義側に追従が必要な参照(読み物リスト・事前調査手順・ドキュメント表など)がないかを別途・明示的に確認する。** プロジェクトの変更が別リポジトリの手順書を陳腐化させても、同じ PR では担保されないため、ここで意識的に拾う(実例: #415 で `doc/DataSpec.md` 新設時、Issue 本文は `flow-js.md` のみ挙げていたが、実際は `flow-python.md` / `SKILL.md` / `CLAUDE.md` のドキュメント表も追従が必要だった)。
4. **後方互換の定型確認** — 過去ログ・既存データへの影響、read/write の非対称(emit は新方式・read はフォールバック等)、フォールバックの要否をユーザーに確認する。
5. **分割の選択肢提示** — 実装が大きい場合、**分割の軸を明示して2〜3案**を提示し、判断はユーザーに委ねる(producer/consumer 軸・言語軸など)。AI が案を勝手に1つに決めない。
### 未解決事項の行き先 — memory ではなく Issue
調査・設計中に見つかった **未解決の作業項目・設計判断・「後でやる」事項** は、その場で解決しないなら**必ず GitHub Issue に反映する**(既存 Issue に追記、なければ新規作成)。**memory には書かない。**
- 理由: Issue 管理の目的(追跡可能・人間も他セッションも追える・作業の単一ソース)は本スキルの前提。未解決事項を memory に入れると検索性が低く分散し、次の作業で recall されず見落とす(実例: #344 で co_announcement 統合の必要性が memory に埋もれ、初回調査で拾えなかった)。
- memory に書いてよいのは「明日この作業の続きをやる」のような**作業途中のセッション状態**だけ。未解決の*仕様・設計・タスク*は Issue へ。
- ユーザーの恒久的な好み・進め方(feedback)は従来どおり memory でよい(それは作業項目ではない)。
### 参照ファイルの読み込み
Issue の変更対象が `src/`(Python)か `frontend/`(JS)かを確認し、対応する参照ファイルを読んでから Phase 3 へ進む:
- **Python 実装**: [`references/flow-python.md`](references/flow-python.md) を読む
- **JS/フロントエンド実装**: [`references/flow-js.md`](references/flow-js.md) を読む
両方にまたがる場合は両方を読む。
---
## Phase 7 — PR 作成
> **前提チェック**: 以下の2つがともにユーザー承認済みであること。
> 1. **AC 対応テスト確認表**(Phase 6「AC 対応テストチェック」)
> 2. **カバレッジ確認結果の表**(Phase 6「カバレッジ突合せ」)
>
> いずれか未提示・未承認の場合は PR 作成前に必ず提示する。
PR の内容を以下のフォーマットで提示し、確認を取る:
```
## PR を作成します
タイトル: {PR タイトル(50文字以内)}
本文:
---
## Summary
- {変更点1}
- {変更点2}
## Implementation notes
- {実装中に追加したリファクタリングがあれば、何を・なぜ・挙動変更の有無を記載}
- {HTML 要素変更に伴う暗黙の挙動・UA スタイル差分があれば記載}
## Test plan
- [ ] `ruff check .` パス
- [ ] `pytest` パス
- [ ] {機能固有のテスト観点}
Closes #{番号}
(複数Issueをクローズする場合は各番号にキーワードを付ける: `Closes #203, closes #205`)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---
このPRを作成してよいですか? [y/N]
```
### Ideas.md の更新
PR 作成前に、`doc/Ideas.md` の該当 Issue 行を削除してコミット・プッシュする(masterへの直接pushは禁止のため、feature ブランチ上でコミット):
```bash
git add doc/Ideas.md
git commit -m "docs: remove issue #{番号} from Ideas.md (completed)"
git push
```
### PR 作成
承認後:
```bash
gh pr create \
--title "{タイトル}" \
--body "..." \
--base master
```
PR URL を表示する。
PR 作成後、**PR レビュー指摘**を受けたら、その指摘が当初 AC の範囲内かを確認する。当初 AC になかった要求が含まれる場合は下の「スコープ拡張ゲート(横断)」へ進む。
---
## スコープ拡張ゲート(横断)
任意のフェーズで発火しうる**割り込みゲート**。Phase 4.5(コードスメル対話)と同じく、特定フェーズに属さず必要なときに起動する。
### 発火条件
**当初 Issue の AC になかった要求**が外部から入ってきたとき。トリガーは実質この2つ:
1. **ユーザーの追加指摘**(対話中に新しい要求・観点が足された)
2. **レビュー指摘**(Phase 7 後、ユーザー・第三者・CODEX 等の PR レビューで AC 外の要求が判明)
> AI が実装中に自発的に「スコープが広がった」と気づくケースは想定しない(実態として起きない)。本ゲートは**外部入力に対するハンドラ**である。これを欠くと contract テストの設計が後追いになり、既存挙動との組み合わせ境界が漏れる(実例: #417 — 「CO 発言以降に継続表示」が後から追加され、「同一 day 内の CO 前発言には表示しない」×「前 day の CO が初期状態として継続表示される」の組み合わせ境界テストが抜けた)。
### 手順
発火したら、まず **追加/変更したい AC の案だけ** を提示する(この時点では Issue 編集も実装もしない):
```
## スコープ拡張ゲート
### 追加/変更したい AC(案)
- [ ] {新 AC 1}
- [ ] {新 AC 2}
### 対処方針のサジェスト
| 観点 | 評価 |
|---|---|
| 追加 AC は独立した受け入れ条件として書けるか | {書ける / 元 AC と密結合} |
| 影響範囲(ファイル・レイヤ) | {元 Issue 内に閉じる / 別レイヤに波及} |
| 追加工数の目安 | {元 SP と同等以下 / 同等以上} |
| 元 AC との組み合わせ境界 | {疎 / 密} |
→ サジェスト: **{取り込む / 別 Issue 化 / 却下}**(理由: ...)
どうしますか?(取り込む / 別 Issue 化 / 却下 / AC 案を修正)
```
> **⚠️ 規模はユーザーが決める**: AI は「大きい/小さい」を勝手に断定して取り込みに流してはならない。
> 上表の客観シグナルを提示し、**最終判断はユーザーに委ねる**。
ユーザーの選択に応じて分岐する:
- **取り込む** — 下記 1→2→3 を順に行ってから、中断していたフェーズへ戻る
- **別 Issue 化** — `idd create`(C-2/C-3)で新 Issue を作成する。現 Issue は当初スコープで閉じ、追加分は新 Issue 側で別途実装する
- **却下** — スコープ外として扱い、当初 AC のまま進める(残す価値があれば `doc/Ideas.md` に追記)
「取り込む」を選んだ場合の手順(**この順序を守る**):
1. **AC 更新** — 上記の AC 案で Issue 本文を更新する(`gh issue edit {番号} --body ... --repo yukkie/AgentVillage`)
2. **contract テスト設計** — 追加 AC に対応する contract テストを設計・追加する。`references/flow-*.md` の「Contract テストの TDD ルール」に従い、**RED を確認してから実装**する
3. **境界ケース列挙** — 追加 AC と既存テストの**組み合わせ境界**を列挙し、漏れを確認する(「新 AC が既存条件と交差する点」を洗い出す)
3 まで終えたら、中断元フェーズの「AC 対応テストチェック」へ戻り、更新後の AC で確認表を作り直す。
---
## Phase 8 — 教訓の振り返り(任意・pull 型)
PR 作成後の**区切り**に到達したら、`wisdom-capture` スキルを起動する。
このセッションで「ユーザーが Claude の提案を否認・修正し、その後に承認へ到達した」判断があれば、それは言語化できる暗黙知の候補。`wisdom-capture` がそれを検出し、ルール化(スキル追記)・Issue 化・寝かせる、を y/N で提案する。発火条件・動作・不変条件(主導権はユーザー・割り込まない・寝かせるを第一選択肢に)は `wisdom-capture/SKILL.md` に定義されているため、ここでは重複させない。
否認がなければ発火しないのが正しい。空振りを避けようと無理に教訓を捻り出さないこと。
---
## エラー処理
| 状況 | 対応 |
|---|---|
| `gh issue view` が失敗 | Issue番号を確認してユーザーに報告。`doc/Ideas.md` の情報だけで設計を続けるか確認する |
| `ruff check .` でエラー | エラーを修正してから次に進む(ユーザーに報告して一緒に直す) |
| `pytest` が失敗 | 失敗したテストの原因を調査して修正する |
| ブランチがすでに存在する | 既存ブランチを使うか新しい名前にするかユーザーに確認 |
Sections and files
Listed in source order.
sections -> サブコマンド: idd create → フロー → サブコマンド: idd import <file> → サブコマンド: idd refine
terms -> なぜ · タイトル · ラベル
files/cmd -> idd create · create · doc/Ideas.md · docs/add-issue-{番号}-to-ideas · Closes #XX · Fixes #XX · Related to #XX · idd import <file>
body sha256 -> 8f5574996f08