docs(subagents): reuse context-warm agents before spawning new ones

[cristim]

Why

Multi-round loops (the §1c review loop, CR-fix rounds, research follow-ups) currently spawn a fresh subagent per round. Every fresh spawn starts cold and re-reads the same files, docs, and diff the previous agent already had loaded, so the bulk of the token spend on iterative work is repeated re-reading rather than new work. Continuing the existing agent via SendMessage makes round N+1 cost only the delta.

What

• CLAUDE.md tenet 4 + §2: new headline rule to check for a context-warm agent (same files, same diff, same investigation thread) and continue it via SendMessage before any fresh Agent spawn, plus a rule for Workflow scripts to batch all same-file steps into one agent() call since those always start cold.
• CLAUDE.md §1c: keep the SAME implementer and SAME reviewer agents alive across review rounds; independence is between the two roles, not between rounds of the same role.
• subagent-strategy.md: new "Reuse agents before spawning new ones (context economy)" section with the pre-spawn check, reuse signals, when NOT to reuse (adversarial independence, tier mismatch, polluted/bloated context, unrelated task), a cost tie-breaker, and structural equivalents for Workflow scripts (partition by file/module rather than by step; pass conclusions between stages instead of re-reading).

Docs-only change; no behavior outside the workflow rules themselves.

Summary by CodeRabbit

• Documentation
  • Expanded agent delegation guidance with explicit rules for context reuse.
  • Added "Reuse agents before spawning new ones" section with conditions for continuation vs. new agent creation.
  • Enhanced subagent strategy recommendations including workflow-specific guidance and decision tie-breaker rules.

[cristim]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 562510d7-b7e7-4c89-9190-16c1e900ab0f

📥 Commits

Reviewing files that changed from the base of the PR and between dd0c6dc and 05cd200.

📒 Files selected for processing (2)

• CLAUDE.md
• subagent-strategy.md

---

📝 Walkthrough

Walkthrough

This PR updates guidance documentation in CLAUDE.md and subagent-strategy.md to introduce and codify a strategy for reusing context-warm agents via SendMessage when follow-up work touches the same files, including detailed reuse criteria and reorganization of the subagent strategy section.

Changes

Agent Context Reuse Strategy

Layer / File(s)	Summary
Reuse strategy introduction CLAUDE.md, subagent-strategy.md	Extended "Delegate to subagents" core tenet to instruct reusing context-warm SendMessage agents when follow-up concerns overlap the same files. Cross-referenced from subagent-strategy.md to the detailed guidance.
Detailed reuse criteria and rules subagent-strategy.md	New section defines when to reuse a warm agent (same files/module, same loop, follow-up on prior research), how to send minimal delta instructions, explicit conditions for not reusing (tier mismatch, independence, context pollution, unrelated tasks), tie-breaker logic, and guidance for workflow scripts.
Subagent strategy reorganization CLAUDE.md	Moved reviewer/implementer separation rules into self-improvement loop area and expanded subagent strategy bullets with rules on full briefing, reusing live agents before spawning new ones, and batching same-file work into single agents in workflow scripts.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~4 minutes

Possibly related PRs

• LeanerCloud/dotclaude#5: Both PRs update CLAUDE.md and adjust the subagent delegation/tier selection guidance (including when to choose cheaper/alternative tiers), so the changes overlap at the documentation rules level.
• LeanerCloud/dotclaude#26: Both PRs update the "Subagent Strategy" documentation to govern subagent dispatch behavior (main PR adds context-warm reuse via SendMessage, retrieved PR adds default background-first via run_in_background), so the guidance changes are related at the shared delegation/agent lifecycle level.
• LeanerCloud/dotclaude#2: Both PRs update CLAUDE.md's "Subagent Strategy"/delegation guidance to change subagent spawning behavior, so the main PR's reworked subagent briefing/reuse rules are closely related to the retrieved PR's delegation-down default.

Poem

🐰 A warm agent waits, context close and keen,
"Reuse me!" it cries for files unseen,
No cold spawn needed when paths align—
Send delta thoughts, keep minds entwined,
One agent fits where two would suffice,
Context warm is always nice. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main change: reusing context-warm agents instead of spawning new ones in subagent workflows.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/agent-reuse

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}