diff --git a/.claude/commands/setup.md b/.claude/commands/setup.md index fcfb723..ee36dd7 100644 --- a/.claude/commands/setup.md +++ b/.claude/commands/setup.md @@ -28,6 +28,46 @@ 3. CLAUDE.md の「開発進捗」と `docs/PROGRESS.md` を確認し，どのフェーズから再開するか判断する 4. 初回の場合はフェーズ 1 から開始する +## 開発モードの選択 (Development Mode) + +新規立ち上げ時（Pre-check で初期状態だった場合），フェーズ 1 に入る前に開発モードを 1 度だけ確定する．既に `.claude/project-mode` がある場合（再開時）はこのステップを飛ばす． + +ユーザーに次を確認する: + +「**このプロジェクトの開発モードを選んでください．** + +- **solo（個人開発）**: 1 人で開発する．進捗は `CLAUDE.md` の進捗欄＋ `docs/PROGRESS.md` で追う． +- **team（チーム開発）**: 複数人が Claude Code で開発する．進捗・タスクは GitHub Issues と git 履歴で追い，直列運用・条件付きセルフマージ等のチームルール（GUIDE_06）を適用する． + +どちらにしますか？（後から変更もできます）」 + +確定したら以下を行う: + +1. `.claude/project-mode` にモード（`solo` または `team` のいずれか 1 語）を書き出す． +2. **solo の場合**: チーム層ファイルが clone で配置されていれば削除し，solo プロジェクトを clean に保つ: + - `docs/01_GUIDE/GUIDE_06_チーム開発ルール.md` + - `docs/01_GUIDE/GUIDE_07_Issues・Projects運用ガイド.md` + - `.claude/commands/task-create.md` / `task-start.md` / `task-handoff.md` + - `.claude/hooks/check_sync.sh` + - ※ `.claude/settings.json` はそのまま（solo でも `restrict_repo_access.py` を使う）．SessionStart(check_sync) の配線は追加しない． +3. **team の場合**: 上記チーム層ファイルを残す．加えて: + - `.claude/settings.json` に SessionStart フックを追記して `check_sync.sh` を配線する（既存の PreToolUse ブロックは保持する）: + ```json + "SessionStart": [ + { + "hooks": [ + { "type": "command", "command": "bash .claude/hooks/check_sync.sh", "timeout": 10 } + ] + } + ] + ``` + - `.gitignore` に `.claude/settings.local.json` が無ければ追記する（個人設定用．GUIDE_06）． + - CLAUDE.md のチーム化は Phase 7 で行う（この時点ではまだ立ち上げ中で Issue/repo が無いため，進捗欄は setup 再開用にそのまま使う）． + +### 進捗記録（立ち上げ中） + +立ち上げ中は repo/Issue がまだ無いため，**モードに関わらず** setup 再開のための進捗は `CLAUDE.md` の進捗欄（最新 1 行）＋ `docs/PROGRESS.md` に記録する．team モードでの「進捗を Issue で追う」への切り替えは Phase 7（実装開始）以降に適用する． + ## フェーズ 1〜6: 各フェーズの実行 GUIDE_01 に定義された各フェーズを順番に実行する． @@ -57,16 +97,29 @@ ## フェーズ 7: 実装開始 1. GUIDE_01 の「CLAUDE.md の管理」セクションに従い，CLAUDE.md を最終更新する + - **team モードの場合**（`.claude/project-mode` が `team`）は，ここで CLAUDE.md をチーム開発向けに変換する: + - 「開発進捗」節を，進捗欄（最新 1 行）ではなく **Issues ポインタ**に置き換える（例: 「進捗・タスクは GitHub Issues と git 履歴で追う（GUIDE_06）．現在のタスクは `gh issue list` で確認する．`CLAUDE.md` には進捗を書かない．」）． + - 「必須ルール（コード実装時）」に **「チーム開発（GUIDE_06 準拠）」小節**を追加する（直列運用・Issue ベースのタスク管理・`/task-create`／`/task-start`／`/task-handoff` の案内・条件付きセルフマージ・共有設定変更は専用 PR＋他メンバー 1 名 Approve 必須）． + - 「Git 運用」小節に，セッション開始時の `[sync-check]` 警告を必ず認識する旨の 1 行を追加する． + - 「ドキュメント」→「01_GUIDE」一覧に `GUIDE_06`・`GUIDE_07` の行を追加する． + - **solo モードの場合**は従来どおり（進捗欄＋ PROGRESS.md 運用）． 2. 作成した全ドキュメントの一覧を表示する 3. 最初の実装ステップを確認する +4. **team モードの場合**は，AI に実施できない「管理者の初期設定」（GUIDE_06「管理者の初期設定」）をユーザーに案内する: + - GitHub リポジトリ作成・メンバー招待 + - Issue テンプレートの用意 + - CI 構築（未構築の間は GUIDE_06「CI 構築までの暫定ゲート」を適用） + - 依存脆弱性対策が必要ならスタックに応じた `.github/dependabot.yml` を追加（エコシステムはプロジェクト固有のため setup では作らない） 「**全フェーズが完了しました．** 作成したドキュメント: {ドキュメント一覧} +開発モード: {solo / team} CLAUDE.md を更新しました． -最初の実装ステップは `{ステップ名}` です．`/implement {タスク}` で開始できます．」 +最初の実装ステップは `{ステップ名}` です．`/implement {タスク}` で開始できます． +{team の場合: 「チーム運用の管理者初期設定（GitHub repo・CI 等）は GUIDE_06 を参照してユーザー側で実施してください．」}」 ## 中断時の処理 diff --git a/.claude/commands/sync-template.md b/.claude/commands/sync-template.md index 0e74b4a..a8b9035 100644 --- a/.claude/commands/sync-template.md +++ b/.claude/commands/sync-template.md @@ -22,6 +22,7 @@ | `CLAUDE.md` | プロジェクト名・開発進捗・固有規約を保持する必要がある | テンプレートで変更された共通セクション（必須ルール，エージェントチーム，ドキュメント構成等）のみを Edit で更新．プロジェクト固有セクションは触らない | | `docs/PROGRESS.md` | プロジェクト固有の進捗ログを保持する必要がある | 既存ファイルがある場合は内容を上書きしない．テンプレート側の骨組み（タイトル・案内コメント）に差分があれば通知のみ行い手動マージを促す | | `.gitattributes` | プロジェクトによって設定が異なる可能性がある | 差分を表示し，ユーザーに「上書き / マージ / スキップ」を問う | +| `.claude/settings.json` | team モードで SessionStart(check_sync) 配線を追加している等，プロジェクト固有の hook 設定を保持する必要がある | 既存の hooks を保持しつつ，テンプレート側で追加・変更された hook のみ統合．差分を表示しユーザーに確認 | マージ処理の対象は **既存ファイルが存在する場合のみ**．初回同期（`.claude/template-sync-sha` がない状態）では全ファイルが A 扱いとなるが，これらのファイルはフレームワーク初期化（`flutter create` / `npm init` 等）や `/init` で既にプロジェクトに存在するのが通常なので，そのままマージ処理に入る．既存ファイルがない稀なケースに限り通常の `cp` で配置する． @@ -35,6 +36,27 @@ 判定はステップ 5.3 のループ内でマージ必須ファイル判定より先に行う． +## モード依存ファイル (Mode-gated / Team-layer Files) + +テンプレートは個人開発（solo）とチーム開発（team）の両モードを 1 つのリポジトリで提供する（GUIDE_06）．以下の**チーム層ファイル**は team モードのプロジェクトにのみ配置し，solo モードのプロジェクトには同期しない． + +| ファイル | レイヤ | +| --- | --- | +| `docs/01_GUIDE/GUIDE_06_チーム開発ルール.md` | team | +| `docs/01_GUIDE/GUIDE_07_Issues・Projects運用ガイド.md` | team | +| `.claude/commands/task-create.md` | team | +| `.claude/commands/task-start.md` | team | +| `.claude/commands/task-handoff.md` | team | +| `.claude/hooks/check_sync.sh` | team | + +判定はプロジェクトの `.claude/project-mode`（`solo` または `team`．`/setup` が作成）で行う: + +- **`team`**: チーム層ファイルを通常どおり同期（A/M/D すべて反映）． +- **`solo`**: チーム層ファイルを同期対象外ファイルと同様に**完全スキップ**（コピー・上書き・削除いずれもしない）．solo プロジェクトは `/setup` 時にこれらを削除済みのため，再配置しない． +- **`.claude/project-mode` が存在しない**（本機能導入前に作られた既存プロジェクト）: 安全側に倒して **`solo` 扱い**とし，チーム層を配置しない．同期の最後に「チーム開発なら `.claude/project-mode` に `team` と記入し再同期してください」と案内する． + +なお `.claude/project-mode` 自体はテンプレートに含まれない（`/setup` が各プロジェクトで生成する）ため，同期で触れることはない． + ## ステップ 1: 事前確認 `git status` でワーキングツリーがクリーンか確認する． @@ -132,8 +154,23 @@ 以降の処理で利用する判定関数を定義する: ```bash -MERGE_FILES=(".gitignore" "CLAUDE.md" "docs/PROGRESS.md" ".gitattributes") +MERGE_FILES=(".gitignore" "CLAUDE.md" "docs/PROGRESS.md" ".gitattributes" ".claude/settings.json") SKIP_FILES=("README.md") +TEAM_LAYER_FILES=( + "docs/01_GUIDE/GUIDE_06_チーム開発ルール.md" + "docs/01_GUIDE/GUIDE_07_Issues・Projects運用ガイド.md" + ".claude/commands/task-create.md" + ".claude/commands/task-start.md" + ".claude/commands/task-handoff.md" + ".claude/hooks/check_sync.sh" +) + +# プロジェクトの開発モードを取得（未設定なら安全側で solo 扱い） +if [ -f .claude/project-mode ]; then + PROJECT_MODE=$(tr -d '[:space:]' < .claude/project-mode) +else + PROJECT_MODE="solo" +fi is_merge_file() { local t="$1" @@ -150,8 +187,18 @@ done return 1 } + +is_team_layer_file() { + local t="$1" + for f in "${TEAM_LAYER_FILES[@]}"; do + [ "$f" = "$t" ] && return 0 + done + return 1 +} ``` +`PROJECT_MODE` が `solo` の場合，チーム層ファイル（`is_team_layer_file` が真）は同期対象外ファイルと同様に完全スキップする（ステップ 5.3 のループでは `is_skip_file` 判定の直後に `[ "$PROJECT_MODE" = "solo" ] && is_team_layer_file "$file"` を追加で判定して `continue` する）．`team` の場合は通常のコピー／マージ判定に進む． + ### 5.3 通常コピー対象の反映（マージ必須ファイル以外） マージ必須ファイルは後段（5.4）で個別処理するため，このループではスキップする．既存ファイルがない場合は通常どおり `cp` で配置する: @@ -165,6 +212,10 @@ if is_skip_file "$file"; then continue fi + # solo モードではチーム層ファイルを完全スキップ（再配置しない） + if [ "$PROJECT_MODE" = "solo" ] && is_team_layer_file "$file"; then + continue + fi # マージ必須ファイルで既存ファイルがある場合は 5.4 で処理 if is_merge_file "$file" && [ -f "$file" ]; then continue @@ -177,6 +228,9 @@ if is_skip_file "$newfile"; then continue fi + if [ "$PROJECT_MODE" = "solo" ] && is_team_layer_file "$newfile"; then + continue + fi if is_merge_file "$newfile" && [ -f "$newfile" ]; then continue fi @@ -250,6 +304,22 @@ - **スキップ**: 既存ファイルを維持 3. 選択に応じて処理する +**`.claude/settings.json` のマージ手順** + +`settings.json` は hooks 設定を持つ．team モードのプロジェクトは PreToolUse（`restrict_repo_access.py`）に加えて SessionStart（`check_sync.sh`）を配線しているため，テンプレート版で盲目的に上書きするとプロジェクト固有の配線が失われる．同期担当エージェント（= あなた）が Read と Edit で JSON をマージする: + +1. 既存 `.claude/settings.json` とテンプレート版 `$TEMP_DIR/.claude/settings.json` を Read する +2. 差分を表示する: + ```bash + diff -u .claude/settings.json "$TEMP_DIR/.claude/settings.json" + ``` +3. **既存の hooks を保持したまま**，テンプレート側で追加・変更された hook（イベント・matcher・command）のみを統合する: + - 既存に無いイベント／hook はテンプレート版から追加する + - プロジェクト固有の hook（team の SessionStart `check_sync.sh` 等）は残す + - 同一 hook の command 変更（例: `restrict_repo_access.py` の起動方法変更）はテンプレート版に合わせる + - solo モードで SessionStart(check_sync) が無い場合は，team 専用の配線を勝手に追加しない +4. `git diff .claude/settings.json` で結果を表示しユーザーに確認する + ### 5.5 削除候補の確認 削除候補（D およびリネーム元）を抽出する: @@ -258,6 +328,8 @@ DELETIONS=$(echo "$CHANGED_ENTRIES" | awk -F'\t' '$1 == "D" {print $2} $1 ~ /^R/ {print $2}') ``` +solo モードではチーム層ファイルはそもそもプロジェクトに存在しないため，削除候補から除外する（`$PROJECT_MODE` が `solo` のとき `is_team_layer_file` が真のパスを `$DELETIONS` から取り除く）． + `$DELETIONS` が空でない場合，ユーザーに確認を求める: 「**以下のファイルはテンプレートから削除されています:** @@ -304,17 +376,24 @@ 「**テンプレート同期が完了しました．** - ブランチ: `{ブランチ名}` +- 開発モード: `{PROJECT_MODE}`（チーム層ファイルは {team: 同期対象 / solo: スキップ}） - 取り込んだ変更: {変更の要約} - コード修正: {あり（内容）/なし} `/commit push` でプッシュと PR 作成ができます．」 +`.claude/project-mode` が存在せず `solo` 扱いにした場合は，末尾に次を添える: + +「※ `.claude/project-mode` が未設定のため solo として同期しました．チーム開発なら `.claude/project-mode` に `team` と記入して再同期してください．」 + ## 注意事項 - テンプレートリポジトリへの push は行わない - コード修正はユーザーの確認なしに実行しない - マージ必須ファイル（`.gitignore`, `CLAUDE.md`, `docs/PROGRESS.md`, `.gitattributes`）は必ずステップ 5.4 の手順でマージする．盲目的な `cp` で上書きしない（フレームワーク固有の除外ルールやプロジェクト固有セクションが失われる） - 同期対象外ファイル（`README.md`）はテンプレート紹介用のためプロジェクトには反映しない．テンプレート側で追加・変更・削除があってもプロジェクトの該当ファイルは触らない +- チーム層ファイル（`GUIDE_06`／`GUIDE_07`／`task-*`／`check_sync.sh`）は `.claude/project-mode` が `team` のプロジェクトにのみ同期する．`solo`（または未設定）のプロジェクトには配置・更新・削除いずれもしない．team 開発に切り替える場合は `.claude/project-mode` を `team` に書き換えてから再同期すればチーム層が配置される（`/setup` を再実行して team を選び直してもよい） +- `.claude/settings.json` はマージ必須ファイル．team の SessionStart(check_sync) 配線を保持したままテンプレートの hook 変更を統合する．盲目的な `cp` で上書きしない - 通常コピー対象でもプロジェクト固有の変更が上書きされうる場合は，`git diff` で確認してユーザーに報告する - テンプレートが管理するのは `.claude/` 配下のうち `agents/`，`commands/`，`hooks/`，`settings.json`，`template-sync-sha` のみ．`.claude/plans/` や `.claude/commit-context.md` 等のプロジェクト固有ファイルはテンプレートに含まれないため同期対象外 - `chore/sync-template` ブランチは他の作業ブランチと混ぜず，作成後は速やかにマージすること．複数の作業ブランチで `/sync-template` を実行すると `.claude/template-sync-sha` がコンフリクトする．コンフリクト時は新しい（HEAD 側の）SHA を採用すること． diff --git a/.claude/commands/task-create.md b/.claude/commands/task-create.md new file mode 100644 index 0000000..051ac85 --- /dev/null +++ b/.claude/commands/task-create.md @@ -0,0 +1,51 @@ +--- +name: task-create +model: inherit +description: "GUIDE_06/07 に従い，Issue を作成しボードに追加する（着手はしない）．タスクの事前計画用．" +argument-hint: "<タスクの説明>" +--- + +あなたはタスク計画担当です． +GUIDE_06（チーム開発ルール）と GUIDE_07（Issues・Projects 運用ガイド）に従い，新しいタスクの Issue を作成してボードに並べてください． + +本コマンドは**タスクを事前に定義する**ためのものです．着手は別途 `/task-start ` で行います（または手動で）．Issue 無しで進める作業はこのコマンドを使う必要はありません（GUIDE_06）． + +## 前提確認 (Pre-check) + +$ARGUMENTS（タスクの説明）が指定されているか確認する．指定がなければ「タスクの説明を指定してください」と伝えて終了する． + +## ステップ 1: Project の特定 (Project Lookup) + +1. リポジトリ所有者を取得する（`gh repo view --json owner --jq .owner.login`）． +2. Project を特定する（`gh project list --owner `）．複数ある場合はユーザーに確認する．見つからない場合はその旨を伝え，ステップ 3（ボード追加）は飛ばして進める（管理者の初期設定が未完了．GUIDE_06）． + +## ステップ 2: Issue 作成 (Create Issue) + +$ARGUMENTS の説明から Issue 本文を組み立てる． + +- **やること**は必ず書く． +- **完了条件（受け入れ基準）**は非自明な場合のみ書く（GUIDE_06）． +- 担当者は**アサインしない**（誰が拾うかは着手時に決まる）． + +`gh issue create --title "<タイトル>" --body "<本文>"` で作成する． + +## ステップ 3: ボードに追加 (Add to Board) + +GUIDE_07「Projects の操作」に従う（Project が無い場合は飛ばす）． + +1. `gh project item-add --owner --url ` でボードに追加する． +2. 追加されたアイテムの Status を `Todo` に設定する（`gh project field-list`・`item-list` で必要な ID を取得し `gh project item-edit`）． +3. `gh project` の書き込み系は成功しても無出力のことがある．`gh project item-list` で結果を確認する（GUIDE_07）． + +## ステップ 4: 完了サマリー (Summary) + +以下を提示する: + +- **Issue**: 番号・タイトル・URL +- **ボード**: Todo +- **次の手順**: 「このタスクに着手する場合は `/task-start ` を実行してください．」 + +## 注意事項 (Notes) + +- 複数タスクを一括で作る場合は，本コマンドを複数回実行してください． +- Projects 操作には `project` スコープが必要．スコープエラーが出たら `gh auth refresh -s project` を実行する（GUIDE_07）． diff --git a/.claude/commands/task-handoff.md b/.claude/commands/task-handoff.md new file mode 100644 index 0000000..b4cede2 --- /dev/null +++ b/.claude/commands/task-handoff.md @@ -0,0 +1,108 @@ +--- +name: task-handoff +model: inherit +description: "現在 In Progress の Issue に進捗メモ（完了済み・残タスク・確定事項・git 状態・再開方法）をコメントで投稿する．セッション中断・引継ぎ用．" +argument-hint: "<追加メモ（省略可）>" +--- + +あなたは作業引継ぎ担当です．現在 **In Progress** の Issue に，次セッション・次メンバーが再開できるだけの情報を進捗メモとして投稿します． + +GUIDE_06（チーム開発ルール）の「進捗は Issues / Projects と git 履歴で追う」方針に沿い，引継ぎ情報を Issue コメントに集約します（`CLAUDE.md` に進捗は書かない）． + +## 前提確認 (Pre-check) + +リポジトリ所有者を取得する（`gh repo view --json owner --jq .owner.login`）． + +## ステップ 1: 対象 Issue の特定 (Identify Issue) + +1. Project を特定する（`gh project list --owner `）．見つからない場合は「Project 未設定のため進捗メモを投稿できません．管理者の初期設定が必要です（GUIDE_06）．」と伝えて終了する． +2. ボードから Status が `In Progress` の Issue を抽出する（`gh project item-list --owner --format json`）． +3. 件数で挙動を変える: + - **0 件**: 「In Progress の Issue がありません．まず `/task-start ` で着手してから本コマンドを使ってください．」と伝えて終了． + - **1 件**: そのまま対象とする． + - **複数件**: 各 Issue 番号・タイトルを示し，「どれを対象にしますか？」とユーザーに確認する． + +## ステップ 2: コンテキスト収集 (Collect Context) + +以下を取得してドラフト生成材料とする． + +- `gh issue view --json number,title,body,comments` で Issue 本文と過去コメントを取得 +- `git branch --show-current` で作業ブランチ +- `git rev-parse --short HEAD` で現在 HEAD +- `git log main..HEAD --oneline` で main から積んだコミット一覧 +- `git status --porcelain` で未コミット変更の有無 +- 直近のセッション会話履歴から「**確定した重要な設計判断**」と「**未決定で次に詰める点**」を抽出 + +## ステップ 3: ドラフト生成 (Draft) + +以下のフォーマットで進捗メモを生成する．**該当なしのセクションは省略してよい**． + +````markdown +## 進捗メモ (YYYY-MM-DD) + + + +### 完了済み + +| フェーズ / タスク | 成果物 | コミット | +| --- | --- | --- | +| ... | ... | <短縮 SHA> | + +### 残タスク + +- ... + +### 確定した重要な設計判断（再開時の文脈） + +- ... + +### 未決定で次に詰める点 + +- ... + +### 現在の git 状態 + +- ブランチ: `<ブランチ名>` +- HEAD: `<短縮 SHA>` +- 未コミット変更: <あり / なし> + +### 次セッションの再開方法 + +```bash +git checkout <ブランチ名> +``` + +<再開時の指針コメント．例: 「`/setup` を再実行するか，手動でフェーズ N から続行」> +```` + +### ドラフトの粒度方針 + +- **完了済み**: 当該セッションで積んだコミット中心．本 Issue に関わる範囲のみ． +- **残タスク**: Issue 本文の TODO や未着手項目を整理． +- **確定した設計判断**: セッション中にユーザーと合意して**今後の作業の前提**になるもの．既に Issue 本文や過去コメントに明記されている内容は重複させない（差分のみ）． +- **未決定で次に詰める点**: 次セッションで判断が必要なもの． +- **粒度感**: 1 セッション分の引継ぎ．週次レポートではない． + +## ステップ 4: 承認 (Approval) + +ドラフトをユーザーに提示し，「**この内容で投稿しますか？ 修正点があれば指示してください．**」と確認する． + +ユーザーの明示的な同意（「OK」「投稿して」「これで」等）が得られるまで投稿しない．修正指示があれば反映して再提示する． + +## ステップ 5: 投稿 (Post) + +`gh issue comment --body "<本文>"` で投稿する．投稿後，コメントの URL を表示する． + +## 完了サマリー (Summary) + +以下を提示する: + +- **Issue**: 番号・タイトル・URL +- **コメント URL** +- **次のステップ**: 「次セッションで再開する場合は `git checkout <ブランチ名>` から始めてください．」 + +## 注意事項 (Notes) + +- 本コマンドは Issue を **Done に動かさない**．In Progress のまま残す（作業継続前提）．完了させたい場合は別途 `/commit merge` で PR をマージ → `Closes #<番号>` で自動クローズ． +- 進捗メモは**コメント**として投稿する．Issue 本文は書き換えない． +- Projects 操作には `project` スコープが必要．スコープエラーが出たら `gh auth refresh -s project` を実行する（GUIDE_07）． diff --git a/.claude/commands/task-start.md b/.claude/commands/task-start.md new file mode 100644 index 0000000..99a21b3 --- /dev/null +++ b/.claude/commands/task-start.md @@ -0,0 +1,61 @@ +--- +name: task-start +model: inherit +description: "GUIDE_06/07 に従い，既存 Issue を拾って作業を開始する（アサイン・ボード In Progress・作業ブランチ作成）．" +argument-hint: "" +--- + +あなたはタスク着手の準備担当です． +GUIDE_06（チーム開発ルール）と GUIDE_07（Issues・Projects 運用ガイド）に従い，**既存 Issue を拾って**作業に取り掛かるための準備を整えてください． + +本コマンドは既存 Issue から作業を始めるためのものです．新規 Issue を立てる場合は `/task-create` を使ってください．Issue 無しで小さい変更や試験的作業を進める場合はこのコマンドは不要です（GUIDE_06）． + +## 前提確認 (Pre-check) + +1. 作業ツリーの状態を確認する（`git status`）．未コミットの変更がある場合は，その旨をユーザーに伝え，先に片付けるか続行するか確認する． +2. 現在のブランチを確認する（`git branch --show-current`）．`main` 以外にいる場合は，そのブランチに未マージのコミットが残っていないか確認する（`git log main..HEAD --oneline`）．残っていれば「前の作業が未マージです．先にマージしてから着手するのが推奨です．続行しますか？」とユーザーに確認する（直列運用．GUIDE_06）． +3. $ARGUMENTS を確認する．Issue 番号（数値または `#数値`）が指定されていなければ「対象の Issue 番号を指定してください．新規 Issue を立てる場合は `/task-create` を使います」と伝えて終了する． + +## ステップ 1: 直列運用チェック (Serial Check) + +GUIDE_06「作業の直列化」より，同時に進行中のコード作業は原則 1 件とする． + +1. リポジトリ所有者を取得する（`gh repo view --json owner --jq .owner.login`）． +2. Project を特定する（`gh project list --owner `）．複数ある場合はユーザーに確認する．見つからない場合はその旨を伝え，ステップ 3（ボード操作）は飛ばして進める（管理者の初期設定が未完了．GUIDE_06）． +3. ボードのアイテムで Status が `In Progress` のものを数える（`gh project item-list --owner --format json`）．対象 Issue 以外で 1 件以上ある場合は，該当タスクを示し「直列運用では進行中の作業は原則 1 件です．続行しますか？」とユーザーに確認する（禁止ではなく原則．GUIDE_06）． + +## ステップ 2: 対象 Issue の確認・アサイン (Verify & Assign) + +1. `gh issue view ` で Issue の内容を確認する．存在しない・クローズ済みの場合はユーザーに知らせて判断を仰ぐ． +2. 担当者が未設定，または自分以外なら，`gh issue edit --add-assignee @me` で自分をアサインする（他人がアサインされている場合は，重複着手にならないかユーザーに確認）． + +## ステップ 3: ボードを In Progress へ (Board) + +GUIDE_07「Projects の操作」に従う（Project が無い場合はこのステップを飛ばす）． + +1. 対象 Issue がボードに未追加なら `gh project item-add --owner --url ` で追加する． +2. 対象アイテムの Status を `In Progress` に変更する（`gh project field-list`・`item-list` で必要な ID を取得し `gh project item-edit`）． +3. `gh project` の書き込み系は成功しても無出力のことがある．`gh project item-list` で結果を確認する（GUIDE_07）． + +## ステップ 4: 作業ブランチ作成 (Branch) + +GUIDE_04 に従う． + +1. `git checkout main && git pull origin main` で `main` を最新化する． +2. GUIDE_04 の基本形式（`[プレフィックス][概要]`）でブランチ名を決める．プレフィックスはタスク種別（`feature` / `fix` / `refactor` / `docs` / `chore`），概要は内容を表す英単語 2〜4 語（kebab-case）とする．ブランチ名に Issue 番号は含めない（GUIDE_06）． +3. `git checkout -b <ブランチ名>` で作業ブランチを作成する． + +## ステップ 5: 完了サマリー (Summary) + +以下を提示する: + +- **Issue**: 番号・タイトル・URL +- **ボード**: In Progress +- **ブランチ**: 作成したブランチ名 +- **次の手順**: 「`/implement` に対象 Issue の内容を渡して実装を開始してください（`gh issue view ` で取得できます）．」 + +## 注意事項 (Notes) + +- branch↔Issue の紐付けは，後の PR 本文の `Closes #` で行う（GUIDE_06）．ブランチ名には番号を入れない． +- Projects 操作には `project` スコープが必要．スコープエラーが出たら `gh auth refresh -s project` を実行する（GUIDE_07）． +- 新規 Issue を立てる場合は `/task-create`，Issue 無しで進める場合は本コマンドを使わず直接 `/implement` 等へ． diff --git a/.claude/hooks/check_sync.sh b/.claude/hooks/check_sync.sh new file mode 100644 index 0000000..f7ece22 --- /dev/null +++ b/.claude/hooks/check_sync.sh @@ -0,0 +1,64 @@ +#!/usr/bin/env bash +# SessionStart hook: ローカルブランチが origin と同期しているかをチェックし, +# JSON で systemMessage (UI 表示) と additionalContext (モデルに注入) を出力する. +# 読み取り専用 (git fetch のみ). 失敗してもセッション開始は阻害しない. +# +# GUIDE_06「直列運用」「main を常に動作可能」を補助する目的で, +# 古い main から作業を始めるミスをセッション開始時に可視化する. + +# JSON 整形は python3 に任せる (jq 非依存. 既存 hook も python3 を利用). +emit() { + local msg="$1" + python3 - "$msg" <<'PY' +import json, sys +msg = sys.argv[1] +print(json.dumps({ + "systemMessage": msg, + "hookSpecificOutput": { + "hookEventName": "SessionStart", + "additionalContext": msg, + }, +}, ensure_ascii=False)) +PY +} + +# git リポジトリ外なら静かに終了 +git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0 + +# origin が未設定なら静かにスキップ (個人 clone・ローカル実験用途) +git remote get-url origin >/dev/null 2>&1 || exit 0 + +# fetch (5 秒で打ち切り). 失敗 = オフライン等. 警告だけ出して継続. +if ! timeout 5 git fetch --quiet origin 2>/dev/null; then + emit "[sync-check] origin への fetch に失敗 — オフラインの可能性" + exit 0 +fi + +BRANCH=$(git branch --show-current) +# detached HEAD は判定できないので静かに終了 +[ -z "$BRANCH" ] && exit 0 + +LOCAL=$(git rev-parse HEAD 2>/dev/null) || exit 0 +REMOTE=$(git rev-parse "@{u}" 2>/dev/null) +if [ -z "$REMOTE" ]; then + emit "[sync-check] $BRANCH は upstream 未設定" + exit 0 +fi +BASE=$(git merge-base HEAD "@{u}") + +DIRTY="" +[ -n "$(git status --porcelain)" ] && DIRTY=" / 未コミット変更あり" + +if [ "$LOCAL" = "$REMOTE" ]; then + emit "[sync-check] ✓ $BRANCH は origin と同期${DIRTY}" +elif [ "$LOCAL" = "$BASE" ]; then + AHEAD=$(git rev-list --count "HEAD..@{u}") + emit "[sync-check] ⚠ $BRANCH は origin より ${AHEAD} コミット遅れ — \`git pull\` 推奨${DIRTY}" +elif [ "$REMOTE" = "$BASE" ]; then + AHEAD=$(git rev-list --count "@{u}..HEAD") + emit "[sync-check] ℹ $BRANCH は origin より ${AHEAD} コミット先行${DIRTY}" +else + AHEAD=$(git rev-list --count "@{u}..HEAD") + BEHIND=$(git rev-list --count "HEAD..@{u}") + emit "[sync-check] ⚠ $BRANCH は origin と分岐 (先行 ${AHEAD} / 遅れ ${BEHIND}) — rebase/merge が必要${DIRTY}" +fi diff --git a/.gitignore b/.gitignore index a066210..f5b74c9 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ +# 個人・マシン固有の Claude 設定（共有 settings.json を汚さない．GUIDE_06） +.claude/settings.local.json + # /implement が /commit に渡すコンテキストファイル .claude/commit-context.md diff --git a/README.md b/README.md index a6b5056..219101e 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,11 @@ Claude Code と協働でプロジェクトを立ち上げ・実装するための汎用テンプレート．`/setup` で対話的に立ち上げ，`/implement` で実装を進める． +**個人開発（solo）とチーム開発（team）の 2 モード**を 1 つのテンプレートで提供する．`/setup` の冒頭でモードを選ぶだけで，チーム開発向けのルール・コマンドが有効化される． + +- **solo**: 1 人で開発．進捗は `CLAUDE.md` の進捗欄＋ `docs/PROGRESS.md` で追う．チーム層ファイルは配置されない． +- **team**: 複数人が Claude Code で開発．進捗・タスクは GitHub Issues と git 履歴で追い，直列運用・条件付きセルフマージ等のチームルール（GUIDE_06）と `/task-create`・`/task-start`・`/task-handoff` コマンド，SessionStart の同期チェック（`check_sync.sh`）が有効になる． + ## Quick Start 新規プロジェクトを始めるときは，以下の手順でテンプレートをカレントディレクトリに展開し，履歴を引き継がない新規リポジトリとして初期化する． @@ -25,14 +30,17 @@ rm README.md ``` -その後 Claude Code を起動し，`/setup ` でプロジェクト立ち上げを開始する．以降，テンプレートの更新を取り込むときは `/sync-template` を実行する． +その後 Claude Code を起動し，`/setup ` でプロジェクト立ち上げを開始する．`/setup` の冒頭で **solo / team のモードを選択**する（選択結果は `.claude/project-mode` に記録され，以降の `/sync-template` がモードに応じてチーム層ファイルを出し分ける）．以降，テンプレートの更新を取り込むときは `/sync-template` を実行する． + +> 個人で始めたプロジェクトを後からチーム開発に切り替える場合は，`.claude/project-mode` を `team` に書き換えて `/sync-template` を実行すれば，チーム層ファイル（GUIDE_06/07・`task-*`・`check_sync.sh`）が配置される．`/setup` を再実行して team を選び直してもよい． ## 主なスラッシュコマンド -- `/setup ` — GUIDE_01 に従いプロジェクト立ち上げを対話的に進行 +- `/setup ` — GUIDE_01 に従いプロジェクト立ち上げを対話的に進行（solo/team を選択） - `/implement <タスク>` — 実装パイプライン（コーディング → テスト → リファクタリング） - `/commit` / `/commit push` — コミット作成（`push` でプッシュと PR 作成まで） - `/sync-template` — テンプレートの最新変更を取り込む +- `/task-create` / `/task-start` / `/task-handoff` — **team モードのみ**．Issue ベースのタスク作成・着手・引継ぎ ## ドキュメント @@ -43,3 +51,5 @@ - `GUIDE_03_ファイル命名規則.md` — ファイル名の規則 - `GUIDE_04_Git運用ルール.md` — ブランチ・コミット・PR の運用 - `GUIDE_05_エージェント運用ルール.md` — `/implement` のエージェントチーム運用 +- `GUIDE_06_チーム開発ルール.md` — **team モードのみ**．直列運用・条件付きセルフマージ・共有設定の扱い +- `GUIDE_07_Issues・Projects運用ガイド.md` — **team モードのみ**．`gh` による Issue/Project 操作手順 diff --git "a/docs/01_GUIDE/GUIDE_05_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" "b/docs/01_GUIDE/GUIDE_05_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" index 2189586..0c2ef4d 100644 --- "a/docs/01_GUIDE/GUIDE_05_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" +++ "b/docs/01_GUIDE/GUIDE_05_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" @@ -143,6 +143,8 @@ ## 進捗記録の運用ルール（CLAUDE.md / PROGRESS.md） +> ⚠ **チーム開発モード（team）では本節は上書きされる**．team プロジェクトでは進捗を `CLAUDE.md`・`docs/PROGRESS.md` に書かず，GitHub Issues と git 履歴で追う（[GUIDE_06](GUIDE_06_チーム開発ルール.md)）．以下は個人開発モード（solo）の既定ルールである．team モードでは Phase 4 の進捗更新を Issue コメント（`/task-handoff` 等）に置き換える． + 進捗記録は **2 ファイルの二段構成**で管理する．Phase 4 や `/setup` 中断時にこれらを更新する． | ファイル | 役割 | 更新方法 | diff --git "a/docs/01_GUIDE/GUIDE_06_\343\203\201\343\203\274\343\203\240\351\226\213\347\231\272\343\203\253\343\203\274\343\203\253.md" "b/docs/01_GUIDE/GUIDE_06_\343\203\201\343\203\274\343\203\240\351\226\213\347\231\272\343\203\253\343\203\274\343\203\253.md" new file mode 100644 index 0000000..44ba076 --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_06_\343\203\201\343\203\274\343\203\240\351\226\213\347\231\272\343\203\253\343\203\274\343\203\253.md" @@ -0,0 +1,142 @@ +# チーム開発ルール (Team Development Rules) + +チーム全員が Claude Code を用い，人間が直接コードを書くことはほぼない前提で，並行開発を破綻させずに進めるための協調ルールを定義する． + +> 本ガイドは**チーム開発モード**（`/setup` で team を選択したプロジェクト）でのみ有効．個人開発モード（solo）のプロジェクトには本ファイル・GUIDE_07・`task-*` コマンドは配置されない． + +Git の手順は [GUIDE_04](GUIDE_04_Git運用ルール.md)，1 タスクの実装パイプラインは [GUIDE_05](GUIDE_05_エージェント運用ルール.md) に従う．本ガイドはそれらの上に立つ「複数人が同時に動くときの調整」を扱う． + +## 基本方針 (Basic Policy) + +- 全員が Claude Code で開発し，実装はエージェントが行う（チーム規模はプロジェクトによる）． +- 原則として並行作業を行わず，1 人ずつ直列で開発する．急ぎではないため，スループットより単純さと `main` の整合性を優先する．これは禁止ではなく既定のスタンスであり，状況に応じた判断は妨げない（詳細は「作業の直列化」）． +- 人間の本質的な役割は「AI にできない判断と確認」（GUIDE_05 と同じ）．加えて「共有設定の番人」を担う． +- 進捗・タスクは GitHub Issues と git 履歴で追う．`CLAUDE.md` には進捗を書かない（この点は GUIDE_05 の進捗記録ルールを**上書き**する）． +- `main` は常に動作可能な状態を保つ（GUIDE_04）．壊れたら他の作業より優先して直す． + +## タスク管理 (Task Management) + +進捗管理の補助として GitHub Issues と Projects を用いる．`gh` コマンドでの具体的な操作手順は [GUIDE_07](GUIDE_07_Issues・Projects運用ガイド.md) を参照． + +### Issue (Issue) + +Issue は**進捗管理の補助**として使う．追跡したい作業に対して立て，PR と紐付けてボードで可視化する． + +- 作業 1 単位 = 1 Issue を推奨する．既に Issue がある作業は，新たに作らずそれに従って進める（重複 Issue を作らない）． +- **Issue は着手・PR 作成・マージのいずれの段階でも必須としない**．小さい変更（typo・1 行修正等）や試験的・探索的な作業は Issue 無しで進めてよい． +- ただし**追跡する価値のある作業には Issue を立てるのが望ましい**（後追いと進捗可視化のため）．特に複数回の `/implement` に跨る作業や，他メンバーに見えていてほしい作業は Issue を作る． +- PR と Issue を紐付ける場合は本文に `Closes #` を記載する．マージ時に Issue が自動クローズされ，ボードのカードも `Done` へ移る． +- Issue 本文には少なくとも「やること」を書く．「完了条件（受け入れ基準）」は非自明な作業のみで構わない． +- 担当者は明確にしておくのが望ましい（重複着手を避けるため）． +- Issue は最初に書き切らなくてよい．`/implement` の Phase 4 で実装サマリーを Issue にコメントし，必要に応じて本文も育てる（GUIDE_05）． + +### Project ボード (Project Board) + +> ⚠ **既定では未使用**．タスク管理は Issue ベース（`gh issue list`）で運用する．Project ボードはチームが拡大したり Issue が常時 10 件超になった等の局面で再導入する想定．以下は将来導入時の参考． + +- 列: `Todo` / `In Progress` / `In Review` / `Done`． +- Issue をカードとして配置し，状態を移動して可視化する． +- マージ連動の自動化を設定し，カード移動の手作業を最小化する（設定は管理者作業．「管理者の初期設定」参照）． + +### タスクの流れ (Task Flow) + +Issue を立てる場合の標準フロー（小さい変更や探索的作業はこの限りでない）． + +```text +1. Issue 起票（完了条件を明記） +2. 自分にアサイン（ボード未使用のためアサインのみ．ボード運用復活時は In Progress へ移動） +3. main から作業ブランチ作成（GUIDE_04） +4. /implement に Issue の内容を渡して実装（GUIDE_05） +5. PR 作成，本文に "Closes #<番号>" +6. セルフマージ条件を確認 → マージ +7. マージで Issue 自動クローズ → カード自動 Done +``` + +- 上記 1 は `/task-create`（事前定義用），2 と 3 は `/task-start `（既存 Issue から着手）で半自動化できる．Issue 無しで進める場合はどちらも不要． +- Claude へのタスク文脈は `CLAUDE.md` ではなく Issue から渡す．`gh issue view ` で取得する． + +## ブランチと PR (Branch & PR) + +[GUIDE_04](GUIDE_04_Git運用ルール.md) に従う．チーム運用上の追加事項のみ以下に定める． + +- ブランチ命名は GUIDE_04 の基本形式（`[プレフィックス][概要]`）に従う．ブランチ名に Issue 番号は含めなくてよい． +- branch↔Issue の紐付けは PR 本文の `Closes #<番号>` で行う．マージ時に Issue が自動クローズされる．既存 Issue からブランチを作る場合は `gh issue develop` でネイティブにリンクできる（GUIDE_07）． +- PR の `--title` はコミットメッセージと同じ書式（`[タグ] 内容`，GUIDE_04）． + +## レビューとマージ (Review & Merge) + +誰も手書きしない体制では，マージ条件が唯一の品質ゲートとなる．本プロジェクトは**条件付きセルフマージ**を採用する．他メンバーの Approve 待ちは原則作らない代わりに，作者自身が満たすべき条件を実質的なゲートとして定める． + +### 通常の機能 PR (Feature PR) + +次を全て満たせば，作者がセルフマージしてよい． + +- CI で全テストが緑である． +- 作者自身が Phase 1 の動作確認（実機・ブラウザ等，AI にできない確認）を済ませている（GUIDE_05）． +- `/implement` のパイプラインをスキップせず完走している． +- 対応 Issue がある場合は完了条件を満たしている（Issue 無しの PR は不要）． +- 共有設定（`CLAUDE.md` のルール部・`.claude/`）の変更を含まない． + +※ レビューは任意．他メンバーはコメントしてよいが，マージをブロックしない． + +### 共有設定を変更する PR (Shared Config PR) + +`CLAUDE.md` のルール部や `.claude/` を変更する PR は，全員の Claude の挙動を変えるため例外とする． + +- 機能 PR に混ぜず，専用 PR とする（「共有設定の扱い」参照）． +- 他メンバー 1 名の Approve を必須とする（セルフマージ不可）． + +### CI 構築までの暫定ゲート (Interim Gate) + +CI が未構築の間は「CI 緑」を以下で代替する．CI 構築後はこの節を削除する． + +- `/implement` を完走している． +- ローカルで全テストが緑である． +- 作者自身が Phase 1 の動作確認を済ませている． + +## 共有設定の扱い (Shared Configuration) + +`CLAUDE.md` と `.claude/`（agents・commands・hooks・settings.json）は全員の Claude の挙動を決める共有インフラである． + +- **git 追跡を継続する**．untrack や `.gitignore` 化はしない（履歴の保全と挙動の統一のため）． +- **進捗は `CLAUDE.md` に書かない**．進捗は Issues と git 履歴で追う（「タスク管理」参照）． +- **変更は「チームルール変更」カテゴリ**として扱う． + - 機能 PR に混ぜない．専用 PR とする（ブランチは `chore/` または `docs/`）． + - 他メンバー 1 名の Approve を必須とする． + - マージ後はチームに周知し，全員が `git pull` して Claude セッションを再起動する． + - ※ Claude はセッション開始時に `CLAUDE.md` を読むため，古いまま動くと文脈がずれる． +- **例外: ドキュメント一覧への追記**は，そのドキュメントを追加する PR と同じ PR で行ってよい．衝突しても両方の行を残せば解決できる． +- **個人・マシン固有の設定**は `.claude/settings.local.json` に置く．これは `.gitignore` 対象とし，共有の `settings.json` を個人都合で汚さない． + +## 作業の直列化 (Serialized Work) + +- 原則として，同時に進行中のコード作業は 1 件とする（進行中の Issue は原則 1 件．Project ボード運用復活時は `In Progress` 列も同様）． +- 次の作業に着手してよいのは，前の作業の PR が `main` にマージされた後とする（マージ条件は「レビューとマージ」参照）． +- タスクは小さく保つ．直列運用では，1 単位が小さいほど次の人の待ち時間が短くなる． +- 直列運用により並行コンフリクトと共有設定のドリフトは原理的にほぼ発生しない．例外的に並行が生じてコンフリクトした場合は GUIDE_04 の rebase 手順をフォールバックとして用いる． +- `main` を壊した場合は他作業より優先して復旧する．自分で対処できない場合は直ちにチームへ報告する（GUIDE_04）． + +## メンバーのオンボーディング (Onboarding) + +新メンバー参加時の手順． + +1. リポジトリへのコラボレーター招待を承認する（GitHub の通知，または `https://github.com///invitations`）． +2. リポジトリを clone する． +3. `ENV_02_環境構築手順.md`（GUIDE_01 参照，立ち上げ時に作成）に従い開発環境を構築する． +4. `gh auth login` で GitHub CLI を認証する．Projects も操作する場合は `project` スコープを含める（GUIDE_07「必要なスコープ」）． +5. 必要なら `.claude/settings.local.json` を用意する（個人設定．git 追跡されない）． +6. 最初に `CLAUDE.md` と `docs/01_GUIDE/` を読む（特に本ガイド・GUIDE_04・GUIDE_05・GUIDE_07）． +7. `.gitignore` が整備されていることを確認する（GUIDE_04）． + +## 管理者の初期設定 (Admin Setup) + +以下は外部サービス操作を含み，AI には実施できない．ルール確定後に管理者（人間）が一度だけ行う． + +- GitHub リポジトリの作成，メンバー招待． +- （既定では未使用）GitHub Project の作成，列（`Todo` / `In Progress` / `In Review` / `Done`）の定義． +- （既定では未使用）マージ連動の自動化設定（PR マージ時に Issue クローズ・カードを `Done` へ移動）． +- Issue テンプレートの用意（「やること」「完了条件」欄）． +- 共有設定変更 PR に他メンバー Approve を求める運用の周知（必要なら `main` のブランチ保護設定）． +- CI の構築（全テストを実行し，緑をマージ条件にできる状態にする）． + +※ 完了するまでは本ガイドの「CI 構築までの暫定ゲート」を適用する． diff --git "a/docs/01_GUIDE/GUIDE_07_Issues\343\203\273Projects\351\201\213\347\224\250\343\202\254\343\202\244\343\203\211.md" "b/docs/01_GUIDE/GUIDE_07_Issues\343\203\273Projects\351\201\213\347\224\250\343\202\254\343\202\244\343\203\211.md" new file mode 100644 index 0000000..629ee09 --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_07_Issues\343\203\273Projects\351\201\213\347\224\250\343\202\254\343\202\244\343\203\211.md" @@ -0,0 +1,136 @@ +# Issues・Projects 運用ガイド (Issues & Projects Operations Guide) + +GitHub Issues と Projects を `gh` コマンドで操作する手順を定義する．人間も AI（Claude Code）も同じコマンドで操作する． + +> ⚠ **Projects の操作は現時点では未使用**．本ガイドの「Projects の操作」セクションは将来導入時の参考として残す．現状の運用は Issue ベースで完結する（[GUIDE_06](GUIDE_06_チーム開発ルール.md)）．Issue 操作・タスクライフサイクルは引き続き本ガイドの該当セクションを参照する． + +タスク管理の方針（Issue = 作業単位，ボードの列，直列運用等）は [GUIDE_06](GUIDE_06_チーム開発ルール.md) に従う．本ガイドはその操作手順を扱う． + +## 基本方針 (Basic Policy) + +- 操作は GitHub CLI（`gh`）に統一する．Web UI でも同じことはできるが，再現性とドキュメント化のため `gh` を基準とする． +- Issue がタスクの単位であり，`/implement` の入力でもある（GUIDE_06）． +- AI に Issue を読ませる場合は `gh issue view ` を使う． + +### 必要なスコープ (Required Scopes) + +`gh` のトークンスコープが操作範囲を決める． + +| 操作 | 必要スコープ | +| --- | --- | +| Issues の読み書き | `repo` | +| Projects の読み書き | `repo` ＋ `project` | + +スコープの確認と追加: + +```bash +gh auth status # 現在のスコープを確認 +gh auth refresh -s project # Projects 用スコープを追加（対話的な再認証が走る） +``` + +## Issues の操作 (Issues) + +### 参照 (View) + +```bash +gh issue list # 一覧 +gh issue list --assignee @me # 自分の担当のみ +gh issue list --state open # 未クローズのみ +gh issue view # 詳細表示 +gh issue view --json title,body,assignees,labels # 構造化出力（AI への受け渡し等） +``` + +### 作成 (Create) + +```bash +gh issue create --title "<タイトル>" --body "<本文>" +``` + +- 本文には「やること」と「完了条件（受け入れ基準）」を必ず書く（GUIDE_06）． +- `--assignee <ユーザー名>`，`--label <ラベル>` で担当・ラベルを同時に指定できる． + +### 更新・コメント・状態変更 (Edit / Comment / State) + +```bash +gh issue edit --add-assignee @me # 自分をアサイン +gh issue edit --add-label "<ラベル>" # ラベル追加 +gh issue comment --body "<コメント>" # コメント追加 +gh issue close # クローズ +gh issue reopen # 再オープン +``` + +## Projects の操作 (Projects) + +※ `gh project` 系は `project` スコープが必要（「必要なスコープ」参照）．`` はリポジトリ所有者（個人またはオーガニゼーション）． + +### 参照 (View) + +```bash +gh project list --owner # プロジェクト一覧（Project 番号を確認） +gh project view --owner # プロジェクトの概要 +gh project item-list --owner # ボード上のアイテム一覧 +gh project field-list --owner # フィールド（Status 等）と選択肢の ID を確認 +``` + +### Issue をボードに追加 (Add) + +```bash +gh project item-add --owner --url +``` + +### カードの状態（列）を移す (Move) + +`Status` フィールドの選択肢（`Todo` / `In Progress` 等）を変更する．フィールド ID と選択肢 ID は `field-list` で確認する． + +```bash +gh project item-edit \ + --id <アイテム ID> \ + --project-id <プロジェクト ID> \ + --field-id \ + --single-select-option-id <移動先の選択肢 ID> +``` + +※ ID の確認が煩雑なため，日常のカード移動は Web UI のボードで行い，一覧取得や自動化に `gh` を使う，という使い分けでもよい． + +## タスクのライフサイクル (Task Lifecycle) + +GUIDE_06 の「タスクの流れ」を `gh` コマンドで具体化したもの． + +※ ステップ 1 は `/task-create <タスクの説明>` で，ステップ 2〜4 は `/task-start ` で半自動化できる．以下は手動でも行える操作の参照． + +1. **Issue 起票**（完了条件を明記） + + ```bash + gh issue create --title "<タイトル>" --body "<やること・完了条件>" + ``` + +2. **アサインしてボードを In Progress へ** + + ```bash + gh issue edit --add-assignee @me + gh project item-add --owner --url # 未追加の場合 + ``` + + ボードの `Status` を `In Progress` に移す（`item-edit` または Web UI）． + +3. **作業ブランチ作成**（GUIDE_04 の基本形式） + + ```bash + git checkout main && git pull origin main + git checkout -b feature/<概要> + ``` + + ※ 既存 Issue から作る場合は `gh issue develop --name feature/<概要> --base main` を使うと，ブランチ作成と Issue↔ブランチのリンクを同時に行える（ブランチ名に依存しないリンク手段）． + +4. **実装**: `gh issue view ` で本文を取得し，`/implement` に渡す（GUIDE_05）． + +5. **PR 作成**: 本文に `Closes #` を記載する（GUIDE_04）． + +6. **マージ**: マージで Issue は自動クローズされ，連動設定があればカードも `Done` へ移る（自動化設定は管理者作業．GUIDE_06「管理者の初期設定」）． + +## トラブルシューティング (Troubleshooting) + +- **`gh project` の書き込み系が無反応に見える**: `create` / `item-add` / `item-edit` は成功しても標準出力が空のことがある．`gh project list` / `item-list` で結果を確認する． +- **`gh project` がスコープエラーになる**: `project` スコープが未付与．`gh auth refresh -s project` を実行する． +- **コラボレーターが操作できない**: 招待を承認していない．`gh api "repos///collaborators" --jq '.[].login'` で承認済みメンバーを確認する． +- **`item-edit` の ID がわからない**: `gh project item-list` でアイテム ID，`gh project field-list` でフィールド ID・選択肢 ID を確認する．