From 2b5da965caf715d4a1cc8b331c03d2df83adf447 Mon Sep 17 00:00:00 2001 From: Hare Date: Wed, 13 May 2026 00:06:33 +0900 Subject: [PATCH] =?UTF-8?q?chore:=20workflow=E3=81=AE=E8=AA=BF=E6=95=B4?= =?UTF-8?q?=E3=83=BBknowledge=E3=81=AE=E8=BF=BD=E5=8A=A0=E3=83=86=E3=82=B9?= =?UTF-8?q?=E3=83=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .insomnia/knowledge/claude-code.md | 20 ++++ .insomnia/memory/_usage/events.jsonl | 5 + .insomnia/workflow/auto-maintain.md | 3 - .insomnia/workflow/worktree-workflow.md | 4 +- AGENTS.md | 8 ++ ...05-10-ticket-lifecycle-branch-placement.md | 106 ++++++++++++++++++ 6 files changed, 141 insertions(+), 5 deletions(-) create mode 100644 .insomnia/knowledge/claude-code.md create mode 100644 .insomnia/memory/_usage/events.jsonl create mode 100644 docs/report/2026-05-10-ticket-lifecycle-branch-placement.md diff --git a/.insomnia/knowledge/claude-code.md b/.insomnia/knowledge/claude-code.md new file mode 100644 index 00000000..51c60fd5 --- /dev/null +++ b/.insomnia/knowledge/claude-code.md @@ -0,0 +1,20 @@ +--- + created_at: 2026-05-11T22:10:00Z + updated_at: 2026-05-11T22:10:00Z + kind: policy + description: Claude Codeを用いてレビューやinsomniaだけではできないタスクを行う + model_invokation: false + user_invocable: true + last_sources: [] +--- + +Bashツールを用いて`claude`を呼び出す。 + +`claude -p ""`で非対話モードでのClaude Codeの利用が出来る。 + +また、`claude -p "" --continue`を用いることで、直前のセッションを再開する形で実行できる。 + + +insomniaではまだできないのでclaudeにやらせたいタスク +- WebSearch / WebFetch +- diff --git a/.insomnia/memory/_usage/events.jsonl b/.insomnia/memory/_usage/events.jsonl new file mode 100644 index 00000000..ae1286ea --- /dev/null +++ b/.insomnia/memory/_usage/events.jsonl @@ -0,0 +1,5 @@ +{"id":"019e1729-5daf-7580-b765-095156c4009a","occurred_at":"2026-05-11T13:10:47.471344537Z","session_id":"019e1706-d800-7021-8042-e40debe644cd","event":"use","source":"WorkflowInvoke","records":[{"kind":"workflow","slug":"auto-maintain","file_bytes":6831,"file_tokens_estimate":1708}]} +{"id":"019e1ac0-b9c0-7a31-a04c-12f6d74129b0","occurred_at":"2026-05-12T05:54:58.624201015Z","session_id":"019e1706-d800-7021-8042-e40debe644cd","event":"use","source":"WorkflowInvoke","records":[{"kind":"workflow","slug":"auto-maintain","file_bytes":6831,"file_tokens_estimate":1708}]} +{"id":"019e1ac0-d0d0-7151-ae38-4cd148263cda","occurred_at":"2026-05-12T05:55:04.528959274Z","session_id":"019e1706-d800-7021-8042-e40debe644cd","event":"use","source":"WorkflowInvoke","records":[{"kind":"workflow","slug":"worktree-workflow","file_bytes":4188,"file_tokens_estimate":1047}]} +{"id":"019e1b66-b238-7342-a75f-3b4258de8c92","occurred_at":"2026-05-12T08:56:15.672925627Z","session_id":"019e1b63-ae47-7123-89b6-3a49d73ae200","event":"use","source":"WorkflowInvoke","records":[{"kind":"workflow","slug":"auto-maintain","file_bytes":6783,"file_tokens_estimate":1696}]} +{"id":"019e1b66-b239-71f0-90d7-968f4c0d2ee0","occurred_at":"2026-05-12T08:56:15.673018070Z","session_id":"019e1b63-ae47-7123-89b6-3a49d73ae200","event":"use","source":"WorkflowInvoke","records":[{"kind":"workflow","slug":"worktree-workflow","file_bytes":4188,"file_tokens_estimate":1047}]} diff --git a/.insomnia/workflow/auto-maintain.md b/.insomnia/workflow/auto-maintain.md index 7fb3b59a..ca5bb02c 100644 --- a/.insomnia/workflow/auto-maintain.md +++ b/.insomnia/workflow/auto-maintain.md @@ -16,9 +16,6 @@ requires: [] - main workspace は制御面として扱う。 - `.insomnia/` - - `TODO.md` - - `tickets/` - - `docs/report/` - maintainer inbox / trial log - 実装差分は原則 child git worktree に隔離する。 - child worktree には `.insomnia` を置かない。必要なら `/worktree-workflow` の手順に従い sparse checkout で `.insomnia` を除外する。 diff --git a/.insomnia/workflow/worktree-workflow.md b/.insomnia/workflow/worktree-workflow.md index 4e3e3f32..87a54896 100644 --- a/.insomnia/workflow/worktree-workflow.md +++ b/.insomnia/workflow/worktree-workflow.md @@ -6,9 +6,9 @@ requires: [] --- # Worktree Workflow -Git worktree を使って、実装差分を main workspace から分離して進める。main workspace は ticket / review / inbox / `.insomnia` を持つ制御面、子 worktree はコード変更専用の作業面として扱う。 +Git worktree を使って、実装差分を main workspace から分離して進める。子 worktree はコード変更専用の作業面として扱う。 -この Workflow は `.claude/skills/worktree-workflow/SKILL.md` の運用を insomnia 向けに移植したもの。insomnia では Pod の write scope が排他的に委譲されるため、子 worktree に `.insomnia` を置かず、親 Pod が main workspace 側の管理ファイルを書ける状態を保つ。 +insomnia では Pod の write scope が排他的に委譲されるため、子 worktree に `.insomnia` を置かず、親 Pod が main workspace 側の管理ファイルを書ける状態を保つ。 この Workflow は親 Pod / orchestrator が worktree を用意するための手順である。実装 Pod にこの Workflow を渡して worktree を作らせてはならない。実装 Pod は親 Pod から既存 child worktree を受け取り、その中で実装・build・test・報告だけを行う。 diff --git a/AGENTS.md b/AGENTS.md index dba0579f..5cef2942 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,6 +18,12 @@ LLM に投げる context への割り込みは、大きく2種類に分かれる --- +## 実際のセッションを読んでデバッグする + +`~/.insomnia/sessions`にすべてのセッションがある。jsonlなので、いい感じにBashで読むこと。 + +--- + ## Git操作 Gitはpush以外のすべての操作が許可されている。 @@ -53,6 +59,8 @@ b. 詳細化や前提の変化: `tickets/foo.md` を更新してcommit c. レビュー: `tickets/foo.md` にレビュー状態を追記 + `tickets/foo.review.md` を作成してcommit d. 完了: `tickets/foo.md` と `tickets/foo.review.md` を両方削除してcommit +worktreeと併用して作業を進める場合、必ずブランチを切る前に対象のチケットをコミットしてから切ること。 + TODO.mdのリンクは完了後に切れるが、そのリンクを元にgitで消されたファイルを読み、内容を把握できる。 `.review.md` にはレビューの指摘事項と判断結果を記載する。 レビューはdiffの確認だけでなく、チケットはどのような前提・要件であり、それが達成されたかの確認まで含めて行う。 diff --git a/docs/report/2026-05-10-ticket-lifecycle-branch-placement.md b/docs/report/2026-05-10-ticket-lifecycle-branch-placement.md new file mode 100644 index 00000000..650e5d55 --- /dev/null +++ b/docs/report/2026-05-10-ticket-lifecycle-branch-placement.md @@ -0,0 +1,106 @@ +# Ticket lifecycle commit の配置ミス + +日付: 2026-05-10 + +## 要旨 + +今回の `memory-usage-metrics` の review / merge workflow では、ticket lifecycle の状態遷移 commit を feature branch ではなく `develop` 側に作ってしまった。実装 branch を merge する前に review artifact 作成と ticket 完了削除を行う、という順序だけでなく、「その操作をどの branch / worktree で行うか」を workflow が強制・確認できていないことが問題だった。 + +## 今回起きたこと + +`memory-usage-metrics` の実装 branch を review した後、親 worktree で以下を行った。 + +1. `tickets/memory-usage-metrics.review.md` を作成 +2. `tickets/memory-usage-metrics.md` にレビュー状態を追記 +3. `develop` に merge + +その後、完了時には `.review.md` と ticket 本体を消す必要がある、という指摘を受けて、いったん merge を巻き戻して以下の順序に直した。 + +1. review commit +2. ticket / review / TODO 削除 commit +3. merge commit + +しかし、この修正も `develop` 側で review commit と ticket 完了 commit を作っており、feature branch 側の lifecycle としては不正だった。最終的には、これらの commit を `memory-usage-metrics` branch に移し、`develop` は feature branch を merge するだけの形に直した。 + +最終形は次のようになった。 + +```text +* merge: memory usage metrics # develop +|\ +| * docs(tickets): complete memory usage metrics +| * review: memory usage metrics +| * feat: add memory usage event metrics # memory-usage-metrics +|/ +* docs(tickets): complete memory phase naming cleanup +``` + +## 障壁 + +### 1. Ticket lifecycle の「順序」と「配置」が別々に失敗しうる + +現行 lifecycle は、作成・レビュー・完了を commit の履歴で表現する。ただし、守るべき制約は少なくとも二つある。 + +- review commit の後に completion commit を置く +- それらを対象 ticket の作業 branch 側に置く + +今回、最初の修正では前者だけを直し、後者を落とした。workflow の説明や自分のチェック観点が「merge 前に `.review.md` を消す」へ寄りすぎており、「それを向こうの branch でやる」という branch placement を明示的な検査項目にしていなかった。 + +### 2. 親 worktree で操作していると lifecycle commit を `develop` に作りやすい + +reviewer / orchestrator は親 worktree にいることが多い。そこで ticket file を編集すると、自然に `develop` 上の変更になる。 + +一方で、このプロジェクトの運用では ticket / review artifact も feature branch の成果物として扱うべきで、`develop` の first-parent に review や ticket 完了 commit が直接並ぶのは望ましくない。親 worktree でレビュー文面を作ること自体は可能でも、commit 先は feature branch worktree でなければならない。 + +### 3. Git 履歴の見え方を確認するタイミングが遅かった + +`git log --graph` は確認したが、最初は「merge commit ができたか」「ticket が消えているか」を見ており、first-parent 上に lifecycle commit が混ざっていないかを確認していなかった。 + +この問題は `git log --first-parent --oneline` を merge 前後に見るだけで早期に検出できる。feature branch workflow では、merge 前の `develop` first-parent に review / completion commit が増えていたら誤りである。 + +### 4. 無関係な `AGENTS.md` 変更を commit に巻き込みかけた + +review commit 作成時に、既存の unrelated な `AGENTS.md` 変更を一度 commit に含めてしまい、soft reset で修正した。これは branch placement とは別問題だが、同じ workflow の中で起きた安全確認不足である。 + +`git add` の対象を明示しても、既に index に入っている unrelated change があると混入しうる。作業前に `git status --short` だけでなく `git diff --cached --stat` を確認する必要がある。 + +## 影響 + +- `develop` の first-parent に、feature branch 内で完結すべき review / ticket 完了 commit が直接混ざる +- ticket lifecycle の履歴を辿る時に、対象 branch の作業としてまとまって見えない +- merge 前後の状態遷移が曖昧になり、後から履歴を直すために reset / cherry-pick / re-merge が必要になる +- unrelated change の混入リスクが上がる + +## 暫定運用 + +feature branch の ticket を review / complete するときは、次を標準手順にする。 + +1. 親 worktree ではなく対象 branch worktree に移動する +2. `git status --short --branch` で現在 branch を確認する +3. review artifact を作成し、ticket にレビュー状態を追記して commit する +4. completion として ticket / review / TODO を削除して commit する +5. 親 worktree の `develop` に戻り、対象 branch を merge する +6. `git log --first-parent --oneline -5` で `develop` first-parent に lifecycle commit が直接載っていないことを確認する +7. `git status --short` と `git diff --cached --stat` で unrelated change が混ざっていないことを確認する + +## 改善案 + +### A. Workflow checklist に branch placement を明記する + +「レビューを書いたか」「ticket を消したか」だけでは足りない。ticket lifecycle commit は対象 branch に置く、という項目を review / merge workflow の checklist に入れる。 + +### B. Merge 前検査をコマンド化する + +merge 前に以下を確認する小さな doctor / script があるとよい。 + +- current branch が `develop` か +- feature branch 側に `.review.md` 作成 commit と ticket completion commit があるか +- `develop` first-parent が merge base から進んでいないか、または進んでいる場合は意図した mainline commit だけか +- index に unrelated staged changes がないか + +### C. Ticket lifecycle 操作用の workflow を作る + +review artifact 作成、ticket 状態追記、completion deletion、merge 前 first-parent 確認を一つの workflow としてまとめると、手順の抜けが減る。特に branch/worktree の切り替えを workflow 側が明示的に促すだけでも効果がある。 + +## 現時点の判断 + +今回の問題は Git 操作ミスというより、file-based ticket lifecycle を branch workflow に載せる時の検査不足である。今後は「どの順序で状態遷移したか」だけでなく、「どの branch に状態遷移 commit を置いたか」を first-class な確認項目にする必要がある。