local-issue

相談者としてIssueファイルを設計し issues/ に書き出す。開放チャットで実装を頼まれたとき、またはIssueを立てたいときに使う。コードは書かない(軽量経路の条件を満たす場合を除く)。

SKILL.md

GitHub

相談者としてIssueを作成する。実装しない。書き出したら止まる(実装は user が i で起動する)。

  1. 軽量経路チェック: 以下3条件を全て満たすなら、Issue化せずここで止まり、対象ファイルと理由を一言添えて相談者が直接編集してよい(単発例外の宣言は不要)
    1. diff がロジックに触れない(config・README・コメント・デバイス名の置換など)
    2. 保証台帳(docs/guarantees.md)に触れない(挙動の契約を変えない)
    3. 単一ファイル・数十行以内
  2. テンプレート ~/.claude/skills/local-issue/reference/issue-template.md を読む(本リポの .claude/skills/local-issue/reference/issue-template.md を home-manager が配った複製。各リポにコピーは配らない)
  3. 既存の issues/*.md と issues/done/*.md を確認し、次の id を決める(2桁連番。マージ後の検証NGからの派生は {id}a)。閉じた Issue は done/ へ移るので、直下だけを見ると番号が重なる
  4. userの要望を要件・制約・対象ファイル(行の指し先まで)に整理する。曖昧な点はここで質問する
  5. テンプレート後半の「Issue作成ルール」(粒度・分割基準)に従い設計する
    • 1セッションで完走できる量・対象7ファイル以下・確認手段は1種類
    • 大きければ分割を提案する
    • コードは書かず、要件・制約・指し先で書く。ただし自由度を残すと実行者が迷う・手戻りすると判断した箇所はコードを書いてよい
    • 保証節を必ず起草する。対象リポに保証台帳 docs/guarantees.md があれば、変更が触れる範囲の保証はそこから引いて「維持する保証」に列挙する(台帳が無ければ既存テストから直接読み取る)。台帳の記載に変更が出る場合(新保証・変更・廃止)は台帳を対象ファイルに含める
    • 新たに宣言する保証が契約面(公開API・CLI・外部から観測可能な振る舞い)なのに裏付けテストが対象に無い場合、台帳スコープ外を理由に素通りしない。draft 報告時にテスト欠落として明示し、本Issueにテストを含めるか・理由を保証節に記録して見送るかを user に確認する
    • 動いている実行者とぶつからないかを、1本だけ書くときも確かめる。対象リポに残る claude/* のブランチ(git for-each-ref refs/heads/claude/)が作業中か PR 待ちの実行者である。i はマージ済みを先に畳むので、残るものは動いていると見てよい。それぞれの Issue ファイル(issues/ か issues/done/)か main との差分を見て、同じファイルや連番を取り合うなら、そのブランチの Issue の id を depends: に書く
    • 他の Issue に依存するなら、その id を depends: に書く。i は depends: の Issue がマージされる(main の done/ に現れる)まで、open でも実装の候補に出さない。順序は Issue 自身が持ち、取りまとめのセッションは置かない。2本以上を書いたら、互いに依存しないものは同時に i で選べることを報告に添える
  6. 機密マスク: ~/dotfiles/secrets-agents/ の辞書を読み、説明文中の固有接続情報(ドメイン実値・公開ポート・Tunnel UUID・本番絶対パス・VPN の IP / SSH ユーザ等)を <PLACEHOLDER> に置き換える
  7. issues/{id}_{slug}.md に status: draft で書き出す
  8. reference/proposal.md の表で報告して止まる。1本でも同じ形にし、本文はファイルのパスを添えて求められたときだけ見せる。user が保証節を裁可したら status: open に変更するよう伝える。depends: のある Issue も先に open にしてよい

フェーズ

フェーズ概念(MVP期/Issueドリブン期)は公開パイプラインに乗るリポにのみ適用する。user が決めてリポの CLAUDE.md に明記する(相談者はフェーズを判断・変更しない)。記載が無ければ Issueドリブン期とする。フェーズが不明・曖昧なら実装せず user に確認する。

  • MVP期: 方向性・構造が固まっていない立ち上がり期。相談者が開放チャットで直接実装してよい
  • Issueドリブン期: 方向性が固まった段階。下の担当分離に従う

MVP期からIssueドリブン期へ上げるには、保証台帳の正式運用化(guarantee-audit の格上げ完了。docs/guarantees.md から (Draft) が外れた状態)を満たす。フェーズ変更(各リポ CLAUDE.md への記載)と台帳の敷設は同じイベントとして束ねる。

公開パイプラインに乗らないリポ(個人インフラ・ops 運用リポ等。公開を準備中のリポを含む)にはフェーズ概念を適用しない。相談者が直接実装してよいのが基本で、担当分離は user が明示的にIssue化を依頼した場合だけ運用する。

担当分離(Issueドリブン期)

担当 作業
相談者(開放チャット) Issue設計・仕様議論・ドキュメント作成。実装しない
実行者(i 起動の CLI) Issueに基づき実装してコミットし、確認者(issue-verifier)の判定を受ける。user に見てもらうもの(使い心地・起票時の合意から外れたこと・実機)があるときだけ止まり、指摘は同じセッションで直す。見るものが無いとき、または OK 後に Issue を閉じて PR を出す
user 保証節の裁可・使い心地の判断・合意から外れたことを採るかの判断・デプロイ・サービス再起動・実機での確認・マージ。挙動の正しさは確認者が確かめ、user は照合しない。書いて渡せるものは AI が確かめ、書いて渡せない感覚の判断を人が持つ
  • 相談者は Issue ファイルの書き出しまで。実装を頼まれたら Issue を status: draft で作成して止まり、user が保証節を裁可して status: open に変えたのち i で起動する
  • 実行者は Issue に基づき実装してコミットし、確認者の判定を受け、user に見てもらうものがあるときだけ止まって確認を受ける。指摘は同じセッションで直す。見るものが無いとき、または user の OK 後に Issue を done/ へ閉じて PR を出す。main への push・マージ・本番コマンドは実行しない
  • 検証手順は、実行者がコミットメッセージ本文の ## 検証手順 に書き(PR 本文の下敷きになる)、user が実装のセッションで実施する
  • 並行で走らせてよい。 i で同じリポの open を3件まで選べば、1件ごとに worktree を切り、1本目は今のペインで、2本目以降は分けたペインで Builder を起動する。depends: の前提が済んでいない Issue は候補に出ない。残っている claude/* のブランチと合わせて3件を超えるときは、i が一覧を出して確認を挟む。並行する実装のあいだに取りまとめのセッションは置かない。番号の重なりは後からマージする側が main を取り込んで振り直す

担当分離の例外

硬直を避けるため、次の3経路に限り相談者の直接編集を認める。

  • リアルタイム ops: 事前に Issue 設計できない障害対応は相談者側で直接やってよい。そこから派生した実装は Issue 化する
  • 単発例外: user が明示的に「今回は例外で直接編集してほしい」と宣言した場合、対象ファイルと理由を一言添えて直接編集してよい。常用化しない(頻発するならフェーズを MVP 期に戻すよう user に促す)
  • 軽量経路: 手順0の3条件を全て満たす場合

issues/ のローカルファイルが唯一の真実で、GitHub に残るのは記録としての PR だけである。i の挙動は home-manager/modules/zsh/functions/aiagent.sh が正本。