docs(lessons): 2026-05-01 のサブエージェント運用教訓 3 件を追記

[fumtas1k]

概要

2026-05-01 のサブエージェント運用で得た教訓 3 件を docs/agent-lessons.md に追記する。共通ルール化の判断は次回の整理時に行う。

追記内容

1. サブエージェントは isolation: "worktree" 必須: 省略時は Bash / mcp__serena__execute_shell_command 等が権限拒否され、ファイル編集しかできず作業未完で停止する（PR fix(config-converter): デバウンス中のダウンロードを抑止 (#149) #181 / chore(rules): エージェント運用ルール強化（ベース確認・push 前チェック・aria 保護） #182 で再現）
2. devDependency 追加時の package-lock.json 同期: PR fix(config-converter): デバウンス中のダウンロードを抑止 (#149) #181 で lock 同期コミットが漏れて CI 失敗寸前。親側の検証手順と復旧コマンドを記載
3. worktree 内部 branch (worktree-agent-<id>) と PR ブランチの取り違え: 既存 PR ブランチ引き継ぎ指示でも worktree が内部 branch を checkout したままコミットが乗るケース。git push origin <internal>:<pr-branch> での復旧手順を記載

動機

これらは類似のケースで再発しやすい運用ハマりどころ。共通ルールに昇格させる前に、まず agent-lessons.md に記録して 1〜2 セッション様子を見る運用とする（shared-agent-rules.md 11 章の方針に従う）。

🤖 Generated with Claude Code

[fumtas1k]

レビュー総評（自 PR のため COMMENT で投稿。実質 LGTM 相当）

docs/agent-lessons.md への追記のみのドキュメント PR で、docs/shared-agent-rules.md 12 章（教訓バッファの運用）および 11 章（昇格判断は別タイミング）の方針に沿った妥当な変更です。コード変更は無く、Tailwind カラークラス禁止等のスタイル規約には抵触しません。コミットプレフィックス docs(lessons): も Conventional Commits の許容範囲内、PR 本文も日本語で base が develop と規約準拠。実質 approve 相当（自 PR のため event は COMMENT）。

良い点

• 各教訓が日付付きで追記され、既存の [2026-04-28] エントリと書式が揃っている。
• 1 件目（isolation worktree 必須）と 2 件目（package-lock.json 同期）が「現象 / 根本原因 / 対処方針」の三段構成で記載されており、再発防止のための具体的アクション（git diff origin/develop --name-only での確認、npm install --package-lock-only での復旧コマンド等）が明示されている点が実用的。
• PR 本文に「共通ルール化の判断は次回の整理時に行う」と明記され、規約 11 章の昇格判断フローを尊重している。
• 2 件目に package.json 直編集 → npm install --no-save のアンチパターンと、~/.npm 所有権問題の回避策（--cache "$TMPDIR/npm-cache"）が併記されており、フォローアップ時の参照価値が高い。

改善提案（軽微・本 PR ブロックせず）

以下はいずれもブロッキングではなく、次回の整理タイミングでの検討で十分です。

1. 3 件目に「根本原因」セクションがなく構成が揃っていない

docs/agent-lessons.md 追記分の 3 件目「worktree 内部 branch (worktree-agent-<id>) と PR ブランチの取り違え」は、1〜2 件目と異なり「現象」と「対処方針」のみで「根本原因」セクションが欠落しています（diff 行 +75 〜 +88 付近）。worktree 作成ツール側のデフォルト挙動（内部生成の worktree-agent-<id> を HEAD に保持し、後続の git checkout -b が無効化される）が原因である旨を 1 行追加すると、読み手の理解と昇格判定がしやすくなります。

2. 「規約昇格候補」と明記された 2 項目の追跡

2 件目末尾（diff 行 +63）と 3 件目末尾（diff 行 +88）に「規約昇格候補」と書かれていますが、docs/shared-agent-rules.md 6.4 章では「先送りは issue 化必須」とされています。教訓バッファ自体の性質上ここで issue 化までは過剰と判断できますが、次の整理時にどう扱うか（昇格 / issue 起票 / 削除）を判断できるよう、PR コメントか後続 PR で扱いを決めると流れがクリアになります。

3. 用語ゆらぎ（refspec）

3 件目の対処方針コードブロック git push origin worktree-agent-<id>:<pr-branch> について、本文では「ref マッピング push」と表記されていますが、Git 一般では「refspec push」と呼ばれることが多いです。整理時に表記統一すると、将来 agent-lessons.md / shared-agent-rules.md 内検索の発見性が上がります。

まとめ

教訓バッファとして適切な追記であり、規約違反は確認できませんでした。上記 3 点はいずれも軽微な構成の揃え方の話なので、次の agent-lessons.md 整理または共通ルール昇格時に併せて対応すれば十分です。マージ問題なしと判断します。

---

Generated by Claude Code

[fumtas1k]

ご指摘の 3 件をすべて反映しました。

1. 根本原因セクション追加: 3 件目「worktree 内部 branch 取り違え」の ### 現象 と ### 対処方針 の間に ### 根本原因 を追加。Agent ツールの isolation: "worktree" が内部生成 branch を HEAD として起動するため、サブエージェントが git checkout -b を実行しても HEAD が変わらない旨を説明しました。

2. 「規約昇格候補」の扱い明記: ファイル冒頭の前置き箇条書き末尾に、「（規約昇格候補）」注記の扱い方（昇格 / issue 化 / 削除のいずれかを次回整理時に判断）を 1 行追記しました。

3. 用語統一: 「ref マッピング push」を「refspec push」に置換（コードブロックは変更なし）。

develop の最新（98b6b38）を rebase 済み。最終コミット SHA: cacf51f9797efb9380937f0f754db672dacf7ce7

Generated by Claude Code

[fumtas1k]

再レビュー（自 PR のため event は COMMENT。実質 LGTM 相当）

前回レビュー（pullrequestreview-4209983481, 2026-05-01 04:49 UTC）以降の更新差分を cacf51f 時点で確認しました。前回指摘 3 点はいずれも適切に反映済みです。docs/agent-lessons.md のみへの追記でコード変更は無く、Tailwind カラー / colors.* / var(--color-*) 等のスタイル規約には抵触しません。コミットプレフィックス docs(lessons): も Conventional Commits の許容範囲、PR 本文も日本語、base が develop と規約準拠です。

前回指摘の対応状況

1. 3 件目に「根本原因」セクションを追加 → 対応済み

docs/agent-lessons.md 84〜86 行目に ### 根本原因 セクションが追加され、Agent ツールの isolation: "worktree" が内部生成された worktree-agent-<id> branch を HEAD として起動するため、サブエージェント側で git checkout -b <pr-branch> origin/<pr-branch> を実行しても HEAD が変わらず後続コミットが意図したブランチに乗らない、という構造的原因が記載されました。1〜2 件目と同じ「現象 / 根本原因 / 対処方針」三段構成に揃っています。

2. 「規約昇格候補」注記の扱いを明示 → 対応済み

ファイル冒頭の前置き箇条書き（docs/agent-lessons.md 8 行目）に、「『（規約昇格候補）』と注記した項目は、次回 agent-lessons.md の整理タイミングで shared-agent-rules.md への昇格 / issue 化 / 削除のいずれかを判断する」と追記され、shared-agent-rules.md 6.4 章「先送りは issue 化必須」の精神に沿った運用方針が明文化されました。教訓バッファ自体の性質と整理タイミングの位置付けが揃ったため、運用上の整合がとれています。

3. 用語ゆらぎ「ref マッピング push」→「refspec push」 → 対応済み

docs/agent-lessons.md 96 行目（3 件目の対処方針）が「refspec push で PR ブランチに上げる」に置換され、Git 一般用語に統一されました。コードブロック git push origin worktree-agent-<id>:<pr-branch> 自体の表記は変更不要のため変更されておらず、適切です。

良い点（前回からの再確認）

• [2026-05-01] の 3 エントリすべてが「現象 / 根本原因 / 対処方針」の三段構成に揃った（前回指摘の構成揃え完了）。
• 対処方針が抽象論ではなく具体的なコマンド（git diff origin/develop --name-only / npm install --package-lock-only --cache "$TMPDIR/npm-cache" / git push origin worktree-agent-<id>:<pr-branch> 等）を含んでおり、再発時にそのまま参照できる実用性がある。
• ~/.npm 所有権問題の補足や、shared-agent-rules.md 6.6 章「/tmp/claude/ 配下に作る」運用とも整合している。
• PR 本文・コミットメッセージ・ベースブランチ（develop）すべて規約遵守。

追加指摘

特にありません。前回指摘 3 点が解消され、教訓バッファとして妥当な追記となっています。

結論

マージ可能と判断します（自 PR のため event は COMMENT、実質 approve 相当）。なお mergeable_state: blocked は CI / レビュー要件側の状態であり、本 PR の内容に起因する問題ではありません。

---

Generated by Claude Code