docs: CLAUDE.md / shared-agent-rules / agent-lessons 整理 + 規約昇格 - #296
Conversation
… 運用補足を昇格 agent-lessons.md からの規約昇格: - 7.1 章 (新設): @layer components 内手書き class は hover:/focus: variant 非対応の警告。 silent regression 事故 (PR #277) と検証手順を明示。 - 6.7 章 (新設): subagent 運用補足。完了報告は項目別ステータス必須 (PR #218 事例) / package.json 変更時 lock 同期確認 (PR #181 事例)。 これで agent-lessons.md の該当 lesson を本ファイルへ集約し、agent-lessons.md は 継続検討中の lesson のみに整理する基盤を作る。
shared-agent-rules.md 11 章「教訓の運用」に従い、規約昇格済 / 完了済 / Claude memory に集約済の lesson を削除。継続検討中の 6 lesson のみに整理。 削除した 6 lesson: - [2026-05-07] Tailwind v4 @layer components hover variant 非対応 → shared-rules 7.1 章へ昇格 - [2026-05-01] subagent isolation:"worktree" 必須 → memory feedback_worktree_and_isolation に集約 - [2026-05-01] worktree 古い node_modules で E2E timeout → 後続 [062] で廃止確認済 (scripts/agent-worktree-setup.sh 削除) - [2026-05-01] PR 本文同期は親 → memory feedback_subagent_workflow (現 shared-rules 6.6) に集約 - [2026-05-01] worktree 内部 branch 取り違え → memory feedback_worktree_merge_order に集約 - [2026-05-02] subagent 絶対パス → memory feedback_worktree_and_isolation に集約 保持する 6 lesson: - [2026-04-28] QRチケット 160px (将来検討事項あり) - [2026-05-01] devDependency lock 同期 (規約昇格候補、但し現状 subagent 完了確認で十分対応可) - [2026-05-02] React effect/memo 矛盾指示 (プロンプト設計 lesson) - [2026-05-02] subagent 完了報告漏れ (規約昇格候補) - [2026-05-04] memory dir Bash rm 不可 (Claude Code harness bug、回避不能) - [2026-05-04] sandbox profile mirror 仮説 (未確認)
旧表記の sub-bullet 詳細 (pre-create check 3 つを各行で展開等) は pr-creation.md 3 章と shared-agent-rules.md 6.x 章で完全カバー済のため、CLAUDE.md は要約 4 点と 正本 pointer に圧縮。同内容の二重管理による drift を防止。
🖼️ Visual Regression Test 結果
|
レビュー所感（多角的評価 + 検証実機実行）
1. 検証 claim の精度（要修正）PR branch (
2. shared-rules 7.1 章で「副次発見: markdown content scan」が欠落agent-lessons.md の Tailwind v4 variant 教訓 (L73-79) には主題 (variant 非対応) 以外に 副次発見 がありました: 新 shared-rules 7.1 章は variant 非対応の主題のみを移管 しており、この副次発見は migrate されていません。 3. shared-rules 6.6 章 ≠ "PR 本文同期は親" lessonPR description は削除 lesson "[2026-05-01] PR 本文の同期はサブエージェントではなく親セッションで行う" を 「shared-rules 6.6 章で代替」 と位置付けていますが、6.6 章 (
であり、 代替案: 新設の 6.7 章「サブエージェント運用の補足」に bullet を 1 行追加 (例: 「PR 本文の更新は親で実行: 4. CLAUDE.md 圧縮で "main 向けはリリース PR のみ" が消失旧 L18: 新 L15-16 (圧縮後): → **「main 向けはリリース PR のみ」**という project policy が消えています。pr-creation.md / shared-rules.md を grep しても "リリース" / "main 向け" の明示記述は見つかりません ( 機能的には develop ベース必須を強化することで間接的にカバーされますが、release-only branch としての main の位置付けは明示されないと、リリース PR を main に向けるオペレーション時に reviewer/agent が判断できません。pr-creation.md か shared-rules 6.3 章 (PR 作成時のベースブランチ) に 1 行追記するか、CLAUDE.md 圧縮版にも残すかを検討してください。 5. 確認できた良い対応 ✅逆に、以下は丁寧に migrate されており問題なし:
6. CI 状態
doc only PR のため e2e は description で省略宣言済。CI gate としては test + VRT で十分。 結論Conditional Approve: CI gate ✅ で merge 可能ですが、以下 4 点を本 PR で対応するか別 follow-up issue で defer するかご判断を:
#1 は数字の事実誤認なので merge 前修正を強く推奨。#2-4 は follow-up issue で defer も可（ 🤖 Generated with Claude Code |
- 7.1 章末尾: markdown content scan 副次発見 (hover:bg-blue-50 等の utility 名リテラルを docs/ 配下から拾って unused utility が build CSS に混入する リスク + src/ コメント内では分割記述する) を追記。 - 6.7 章: 「PR 本文の更新は親で実行」 bullet を追加。gh pr edit --body-file は ask permission で subagent から非対話 deny される (PR #189 事例)。 - 6.3 章: 「main 向けはリリース PR のみ」を明記。release-only branch policy。 PR #296 review (Conditional Approve) で指摘された 4 件のうち #2 / #3 / #4 の対応。#1 (PR description 数字) は別途 gh pr edit で対応。
|
レビューありがとうございます。4 件すべて本 PR で対応しました (commit 対応内容1.
|
再レビュー（指摘 4 件の対応確認 + 実機再検証）
#2 / #3 / #4: shared-rules への追記内容確認 ✅
6.3 章 (release-only branch policy):
✅ 過不足なし。base 制約 + リリース時の運用フローが 1 行で完結。 6.7 章 (PR 本文の更新は親で実行):
✅ 削除された lesson の actionable rule (subagent → 親引き取りフロー + 過去事例 PR #189) を完全に保持。6.7 章のテーマ「サブエージェント運用の補足」とも整合。 7.1 章 (markdown content scan 副次発見):
✅ 私が指摘した「 #1: PR description 数字更新 — 一部 caveat あり更新後の PR description: 評価: ✅ 改善。本 worktree / CI Linux 環境の差を併記する形になり、reader が文脈を追える。 ただし私の手元での再検証では、 → 750 passed / 0 skipped が観測され、 数字精度が気になる場合は、PR description を CI 状態
doc only PR で e2e 省略宣言済 (PR description 4 項目)、test + VRT で gate 充足。 結論Conditional Approve → Approve に格上げします。
🤖 Generated with Claude Code |
1 participant
概要
CLAUDE.md /
docs/shared-agent-rules.md/docs/agent-lessons.mdおよび Claude memory (~/.claude/projects/.../memory/) が増えすぎて重複・drift リスクが顕在化していたため、SoT を repo doc 側に集約して整理。memory は本 repo 管理外 (gitignore 対象) のため本 PR には含まれないが、本 PR と並行して整理 (39 → 25 個に削減、内訳は本文 §3 参照)。
1. shared-agent-rules.md への規約昇格 (新規 2 sub-section)
7.1 Tailwind v4
@layer componentsの variant 非対応hover:bg-subtleのような Tailwind hover utility と@layer components手書き class の併用が silent regression を起こす事故 (PR #277) を再発防止。専用 hover class (.hover-bg-subtle等) を:hover擬似クラスごと定義する pattern を明文化。6.7 サブエージェント運用の補足
package.json変更時はpackage-lock.json同期確認 (PR fix(config-converter): デバウンス中のダウンロードを抑止 (#149) #181 で lock 不整合のまま push される寸前で発覚)2. agent-lessons.md からの 6 lesson 削除
shared-agent-rules.md 11 章「教訓の運用」に従い、規約昇格済 / 完了済 / memory 集約済 の lesson を削除して継続検討中の 6 lesson のみに整理。
削除した 6 lesson:
[2026-05-07] Tailwind v4 @layer components hover variant→ shared-rules 7.1 章へ昇格[2026-05-01] subagent isolation:"worktree"必須 → memoryfeedback_worktree_and_isolationへ集約[2026-05-01] worktree 古い node_modules で E2E timeout→ decisions [062] で廃止確認済[2026-05-01] PR 本文同期は親→ shared-rules 6.6 章で代替[2026-05-01] worktree 内部 branch 取り違え→ memoryfeedback_worktree_merge_orderに集約[2026-05-02] subagent 絶対パス→ memoryfeedback_worktree_and_isolationに集約保持の 6 lesson は将来検討中の事項 (QRチケット 160px / devDependency lock / React effect/memo 矛盾指示 / subagent 完了報告漏れ / memory dir Bash rm 不可 / sandbox profile mirror 仮説)。
3. Claude memory 整理 (本 PR scope 外、参考)
repo doc と完全重複する memory 11 個を DEPRECATED stub 化、近接 3 個を
feedback_worktree_and_isolation.md1 個に統合。MEMORY.md index は 41 → 25 行に。詳細は本 PR scope 外 (memory は gitignore)、別途 user 環境で物理削除予定。4. CLAUDE.md 軽量化
「PR 作成 4 点必須」 (L15-22) の sub-bullet 詳細 (pre-create check 3 つを各行で展開等) は pr-creation.md 3 章 + shared-rules 6.x 章で完全カバー済のため、要約 + 正本 pointer に圧縮 (8 行 → 5 行)。同内容の二重管理による drift を防止。
検証
npm run test全 659 件 pass + 1 skipped (合計 660、本 worktree 環境でinline-style-migration系の skipIf 評価で 1 file skip。CI Linux 環境では 750 件相当)node_modules/.bin/astro check0 errors / 0 warningsnpm run test:e2e: 本 PR は doc only でコード変更ゼロのため省略 (docs/playbooks/e2e-validation.md1 章「バグ修正・UI 挙動の変更時」基準に該当しない)関連
#176B 案 PR 7a)<element style="...">属性 65 件の CSS class 移行 #289 (Astro inline migration、進行中)docs/shared-agent-rules.md11 章「教訓の運用」 — 共通ルール化 → agent-lessons から削除のフローレビュー時の注目点