Claude Code Subagents गाइड: article और code work को सुरक्षित तरीके से delegate करें

Claude Code में काम बड़ा होते ही सबसे पहले model नहीं टूटता, workflow टूटता है। अगर एक ही conversation में research, writing, translation, code edit, checks और review सब डाल दिए जाएं, तो context बहुत भारी हो जाता है। Agent वही files बार-बार पढ़ता है, command logs जगह घेरते हैं, और अंत में यह साफ नहीं रहता कि कौन-सी file क्यों बदली गई।

Subagent इसी समस्या को कम करने का तरीका है। यहां delegation का मतलब “दूसरे agent को सब कुछ सौंप दो” नहीं है। इसका मतलब है छोटा सा contract देना: लक्ष्य क्या है, कौन-सी files edit कर सकता है, कौन-सी files नहीं छूनी हैं, done कब माना जाएगा, और result किस format में वापस आना चाहिए। यह contract parallel work को duplicated work बनने से रोकता है।

यह guide ClaudeCodeLab के article production workflow से निकली है: पहले Japanese canonical article बनाना, फिर 10 languages में localize करना, prompt templates verify करना, और publishing से पहले review करना। यही pattern code changes, documentation, migration planning और release preparation में भी काम आता है।

Subagent क्या है

Subagent एक specialized worker है जो main conversation से अलग context में चलता है। Context यानी Claude की current working memory: chat history, पढ़ी गई files, command output, project rules और temporary summaries। जब कोई task बहुत सारे search results, logs या translation drafts पैदा करता है, तो subagent heavy reading कर सकता है और main conversation में सिर्फ useful summary वापस ला सकता है।

Official reference के लिए Claude Code docs में subagents, memory और slash commands देखें। Practical बातें ये हैं: subagents isolated context से शुरू होते हैं, project agents .claude/agents/ में रखे जा सकते हैं, और subagent की बहुत लंबी final response भी main context को consume करती है।

Term	आसान मतलब
subagent	research, implementation, translation या review करने वाला specialized worker
context	Claude को अभी दिख रही working memory
disjoint write set	ऐसे editable files जिनमें दूसरे worker से overlap न हो
explorer	read-only research agent, जो पहले scope समझता है
worker	agent जो सिर्फ assigned files edit करता है
handoff contract	scope, constraints, done condition और return format का छोटा contract

कब delegate करें

हर task को subagent को देना सही नहीं है। छोटी change में delegation उल्टा slow हो सकता है, क्योंकि हर agent को context फिर से बनाना पड़ता है। सही सवाल है: क्या context अलग करने से value मिलेगी, और क्या files बिना overlap के बांटी जा सकती हैं?

काम	Delegate करें?	कारण
एक article को 10 languages में localize करना	हां	हर locale की अपनी file है और quality criteria clear हैं
बड़े codebase में existing pattern ढूंढना	हां	main thread को पूरा output नहीं, सिर्फ map चाहिए
एक typo ठीक करना	नहीं	coordination cost काम से ज्यादा है
auth modules का बड़ा refactor	पहले explore करें	impact scope clear करना जरूरी है
unclear requirements वाली new feature	अभी नहीं	पहले main conversation में requirements clear करें

मेरी practical rule यह है: delegate तभी करें जब task बहुत intermediate output पैदा करे, हर worker को exact files तक सीमित किया जा सके, और final answer checklist, table या short receipt में आ सके।

Core pattern: explorer, worker, reviewer

बड़े काम में सीधे कई editing agents शुरू न करें। पहले explorer चलाएं। Explorer read-only mode में relevant files, existing conventions, risks और suggested write sets देता है। उसके बाद workers अलग-अलग file sets edit करते हैं। आखिर में reviewer या verification agent read-only mode में result check करता है।

flowchart TD
  A["Main: goal and constraints"] --> B["Explorer: read only, map scope"]
  B --> C["Main: decide disjoint write sets"]
  C --> D["Worker: canonical article or code module"]
  C --> E["Worker: localized files or separate module"]
  D --> F["Reviewer: quality, metadata, verification"]
  E --> F
  F --> G["Main: final checks and handoff"]

यह sequence सबसे common failure रोकता है: task broad होने की वजह से कई agents same files पढ़ते और edit करते हैं।

Use case 1: multilingual article production

ClaudeCodeLab में safe workflow है कि पहले Japanese canonical article पूरा किया जाए, फिर पूरी guide को localize किया जाए। Canonical यानी base article। अगर base article thin है, तो translations भी thin होंगी। अगर base article में examples, pitfalls, templates और CTA हैं, तो हर language substance maintain कर सकती है।

Role	Allowed files	काम
ja-worker	site/src/content/blog/claude-code-subagent-patterns.mdx	structure, examples, prompts और CTA बनाना
western-locale-worker	blog-en, blog-es, blog-fr, blog-de, blog-pt	बिना summarize किए natural localization
asia-locale-worker	blog-zh, blog-ko, blog-hi, blog-id	local readers के लिए terms adjust करना
review-agent	सभी 10 slug files, read-only	frontmatter, mojibake, links, code fences और publishing risk check करना

Translation worker के लिए copy-paste prompt:

Use a translation subagent for the assigned locale files only.

Source:
- Japanese canonical file: site/src/content/blog/claude-code-subagent-patterns.mdx

Allowed write set:
- site/src/content/blog-en/claude-code-subagent-patterns.mdx
- site/src/content/blog-es/claude-code-subagent-patterns.mdx

Rules:
- Do not summarize. Localize the full guide.
- Keep frontmatter valid and preserve heroImage.
- Use natural SEO terms for each language.
- Keep prompt templates copy-pasteable.
- Do not edit Japanese or other locale files.

Return:
- Files changed
- Localization choices
- Any terms that may need human review
- Checks performed

Use case 2: article code examples verify करना

Article writer और verification agent की role अलग होनी चाहिए। Writer explanation, structure और reader value पर focus करता है। Verification agent code fences extract करता है, syntax देखता है, file paths validate करता है, और बताता है कि कौन-सा snippet copy-paste करने लायक है।

---
name: article-reviewer
description: Reviews ClaudeCodeLab articles for originality, implementation detail, SEO, and publication risk.
tools: Read, Grep, Glob
---

You review article drafts critically.
Check whether the draft has concrete examples, pitfalls, working prompts,
official links, internal links, and a clear CTA.
Return findings first, then a short pass/fail recommendation.

यह definition .claude/agents/article-reviewer.md में रखी जा सकती है। name unique होना चाहिए और description में यह clear होना चाहिए कि agent कब use करना है। बहुत लंबी policy prompt में न डालें; persistent rules CLAUDE.md या team checklist में ज्यादा maintainable हैं। Related guidance के लिए context management guide और CLAUDE.md best practices देखें।

Use case 3: code changes को disjoint write sets में बांटना

Code work में भी वही principle काम करता है। मान लें blog site में article cards, OGP image generation और related posts logic बदलना है। Features connected हैं, लेकिन files अलग-अलग हैं।

We will use three workers with disjoint write sets.

Worker A:
- May edit: site/src/components/BlogCard.astro
- Must not edit: layouts, pages, content files
- Goal: improve card metadata rendering only

Worker B:
- May edit: site/src/pages/og/[...slug].png.ts
- Must not edit: components or article files
- Goal: verify OGP title and hero behavior

Worker C:
- May edit: site/src/lib/relatedPosts.ts
- Must not edit: components, pages, content files
- Goal: improve related-post selection without changing routes

All workers return a handoff receipt with changed files, reasoning, tests, and risks.

Weak prompt है: “UI parallel improve करो।” Strong prompt है: “यह file edit कर सकते हो, यह file नहीं छूनी, और यह evidence वापस चाहिए।”

Use case 4: read-only review और verification

अंतिम agent अक्सर read-only होना चाहिए। Reviewer reader value, SEO gaps, duplicate content और missing pitfalls देखता है। Verification agent metadata, links, commands, code fences और build risk देखता है।

Use a review subagent in read-only mode.

Scope:
- Read only these 10 localized files for slug claude-code-subagent-patterns.
- Do not edit anything.

Review checklist:
- description is 120 characters or fewer
- updatedDate is 2026-06-02
- heroImage is retained
- each locale is a full localized article, not a thin summary
- at least 3 concrete use cases are present
- pitfalls and failure modes are concrete
- code fences are balanced
- official external links and internal links are present
- CTA is natural and relevant

Return findings by severity with file paths and line numbers where possible.

Multilingual publishing में यह step बहुत useful है। कोई भाषा natural लग सकती है, पर date पुरानी हो सकती है, code fence खुला रह सकता है, या CTA missing हो सकता है। Code work के लिए इसे Claude Code code review checklist के साथ use करें।

Delegation templates

Main conversation के लिए orchestration prompt:

You are the orchestrator. Before using subagents, create a delegation plan.

Goal:
- [one sentence goal]

Hard constraints:
- Work only on: [exact files or directories]
- Do not edit: [out of scope]
- Preserve: [metadata, public API, routes, screenshots, etc.]
- Verification required: [commands or manual checks]

Ask explorer agents to read first. Do not start workers until write sets are disjoint.
For every worker, define:
- allowed write set
- forbidden files
- expected output
- done condition

Final response must include:
- changed files
- checks run
- remaining risks

Read-only discovery के लिए:

Use an explorer subagent in read-only mode.

Task:
- Map the current state of [feature/article/slug].
- Find existing conventions, related files, internal links, and quality gaps.

Rules:
- Do not edit files.
- Prefer search and targeted reads over full-directory dumps.
- Return only the useful summary, not raw command output.

Return:
- Files that matter
- Existing patterns to follow
- Risks or unclear requirements
- Suggested write sets for workers

Implementation worker के लिए:

Use a worker subagent for this isolated edit.

Allowed write set:
- [file 1]
- [file 2]

Forbidden:
- Do not edit files outside the allowed write set.
- Do not stage, commit, push, deploy, or rewrite unrelated changes.
- If the task requires another file, stop and report why.

Implementation goal:
- [specific behavior or article quality outcome]

Return a handoff receipt:
- Files changed
- Summary of changes
- Commands or checks run
- Evidence of success
- Remaining risk

Common failures

पहली गलती है boundaries तय करने से पहले parallelize करना। अगर तीन workers को “article improve करो” दिया गया, तो तीनों title, intro, examples और CTA edit करेंगे। Diff बड़ा होगा, control कम होगा।

दूसरी गलती है बहुत लंबा result वापस लाना। Subagent काम करते समय main context बचाता है, लेकिन final response वापस आते ही context consume करती है। Full logs की जगह decisions, tables और receipts मांगें।

तीसरी गलती है weak handoff contract। “Natural translate करो” काफी नहीं है। लिखें: summarize मत करो, frontmatter preserve करो, pitfalls रखो, local SEO terms use करो, और human review वाली phrases बताओ।

चौथी गलती है implementer से अपनी assumptions खुद verify करवाना। Reviewer को skeptical mode में पढ़ने, constraints से compare करने और पहले risks बताने को कहें।

पांचवीं गलती है agent definitions के loading behavior को भूलना। .claude/agents/ में नया file रखने के बाद fresh session में confirm करना ज्यादा safe है। Reusable agent के लिए short file definition बहुत लंबे one-off prompt से बेहतर रहती है।

Context budget rules

Subagents तभी context बचाते हैं जब आप return size control करें।

Context budget rule:
- Explorer returns at most 20 bullets and 1 table.
- Worker returns changed files, decisions, and checks only.
- Reviewer returns findings by severity, no full rewritten article.
- Logs longer than 80 lines must be summarized.
- If uncertainty remains, ask one focused question instead of dumping raw output.

Final article या code बड़ा हो सकता है, लेकिन handoff short होना चाहिए। दोनों को mix करने से main conversation drafts, translation notes और verification logs से भर जाती है।

Copy-paste read-only reviewer

सबसे सुरक्षित पहला subagent read-only reviewer है। यह script .claude/agents/article-reviewer.md बनाती है। Agent draft पढ़कर risk बता सकता है, लेकिन file edit नहीं कर सकता, इसलिए publication से पहले critical review जोड़ने का यह low-risk तरीका है।

mkdir -p .claude/agents
cat > .claude/agents/article-reviewer.md <<'EOF'
---
name: article-reviewer
description: Reviews ClaudeCodeLab articles for originality, implementation detail, SEO, and publication risk.
tools: Read, Grep, Glob
---

Review the assigned files only. Do not edit.

Checklist:
- title and description match the search intent
- intro gives a concrete reader problem in the first three lines
- examples, pitfalls, official links, internal links, and CTA are present
- code fences are balanced and labeled
- the article is not a thin summary or duplicated from another page

Return:
- findings by severity
- pass/fail recommendation
- one highest-leverage fix
EOF

Delegation checklist

# Subagent Delegation Checklist

## Before delegation
- [ ] Goal is one sentence.
- [ ] In-scope files are listed explicitly.
- [ ] Out-of-scope files and actions are listed explicitly.
- [ ] Explorer runs before worker when scope is unclear.
- [ ] Write sets do not overlap.

## During work
- [ ] Each worker edits only allowed files.
- [ ] Large outputs are summarized.
- [ ] Any need to expand scope is reported before editing.
- [ ] Prompts include done conditions.

## Review
- [ ] Reviewer runs in read-only mode.
- [ ] Metadata and links are checked.
- [ ] Code fences and commands are checked.
- [ ] Localization is full, not summarized.
- [ ] Remaining risks are written in the handoff.

Practical result

ClaudeCodeLab article work में सबसे बड़ा improvement translation speed से नहीं आया। Improvement आया canonical draft, locale workers और read-only reviewer को अलग करने से। पहले कभी-कभी एक language strong रहती थी और बाकी versions thin summary बन जाती थीं। अब no-summary rule, fixed write sets और verification receipt के कारण final review ज्यादा concrete होता है।

अगर आपकी team Claude Code adopt कर रही है, तो subagents को magic automation button की तरह नहीं, बल्कि work design pattern की तरह सिखाएं। ClaudeCodeLab ऐसे delegation contracts, review rubrics और context habits को team-oriented training और product templates में व्यवस्थित करता है।