From a4c51035974734327ba5a51bf4eb7fcc1a930b13 Mon Sep 17 00:00:00 2001 From: chen <546775624@qq.com> Date: Tue, 12 May 2026 21:26:40 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E5=AD=A6=E4=B9=A0=E7=AC=94?= =?UTF-8?q?=E8=AE=B0=EF=BC=9A=E5=8E=9F=E5=A7=8B=E6=96=87=E7=AB=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Claude Multi-Agent Systems.md：完整指南原文 - 34% of your Claude Code tokens go to hook fights：Hook冲突问题原文 Co-Authored-By: Claude Haiku 4.5 --- ...% of your Claude Code tokens go to hook fights | 199 +++++++++ 学习笔记/Claude Multi-Agent Systems.md | 415 ++++++++++++++++++ 2 files changed, 614 insertions(+) create mode 100644 学习笔记/34% of your Claude Code tokens go to hook fights create mode 100644 学习笔记/Claude Multi-Agent Systems.md diff --git a/学习笔记/34% of your Claude Code tokens go to hook fights b/学习笔记/34% of your Claude Code tokens go to hook fights new file mode 100644 index 0000000..a9806db --- /dev/null +++ b/学习笔记/34% of your Claude Code tokens go to hook fights @@ -0,0 +1,199 @@ +34% of your Claude Code tokens go to hook fights. Here's the 3-line fix. +You installed 38 agents. You added Superpowers, claude-mem, AgentShield, ECC. Two PostToolUse hooks edit the same file. Three agents claim the same matcher. Your token bill is up 40% and Claude keeps "forgetting" your CLAUDE.md. +You think the model is dumb. It isn't. Your agents are fighting each other. +I spent 11 days putting an HTTP proxy between Claude Code and the Anthropic API, logging every hook execution across 14 different setups. +The pattern is consistent. The fix is three lines. +Here's what's actually happening, and how to stop it tonight. +The proof +I instrumented 14 Claude Code setups for 11 days. All of them used 3+ plugins from the official marketplace. Half had ECC installed. +All of them ran into one of three failure modes: +PostToolUse cascade. +A hook modifies a file, which fires another PostToolUse, which fires another. One developer's setup ran 7 chained PostToolUse events on a single Edit. 7x token cost. He thought Claude was "running slow." +Matcher overlap. +Two agents both register matcher: "Edit|Write" for code review. They run in series. They produce contradictory recommendations. Claude tries to obey both. Code quality drops. +Hook injection conflicts. +UserPromptSubmit hook from skill A injects context. Another from skill B injects different context. Claude reads both as "user said X" and gets confused about what you actually asked. +Average token waste across the 14 setups: 34% of every session, gone before Claude generated a single useful token. +Worst case: one developer was burning his Claude Max 20x weekly limit by Wednesday. After the fix below, he was hitting limits Sunday evening. Three full days of additional capacity from changing 3 lines in settings.json. +How I measured this +The HTTP proxy sat between Claude Code and the Anthropic API, logging every request and response with timestamps, token counts, and the full hook execution trace. Each setup ran for ~11 days of normal work: real projects, real edits, real prompts. Not synthetic benchmarks. +For each session, I counted: +Total tokens billed +Tokens spent on hook-injected context (UserPromptSubmit, SessionStart) +Tokens spent on PostToolUse cascade re-fires (same hook, same edit, fired more than once) +Tokens spent on contradictory subagent outputs that Claude then had to reconcile +The "34% wasted" number is the sum of categories 2-4 divided by the total. Wide variance across the 14 setups: cleanest setup wasted 18%, dirtiest wasted 52%. Median 34%. Every single setup lost more than 15% to fights. There were no clean rooms. +The fix below targets the largest of those buckets, cascades, because it's both the easiest to fix and the one that compounds fastest as you install more plugins. +Why this happens +Claude Code v2.1.116+ supports 26 hook lifecycle events: PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, SessionEnd, Stop, SubagentStart, SubagentStop, PreCompact, PostToolUseFailure, PermissionRequest, PermissionDenied, Notification, TaskCreated, CwdChanged, FileChanged, and more. +Each one fires when the matching event happens. Each plugin can register hooks on any of them. +There is no global ordering rule between plugins. +When plugin A registers a PostToolUse hook on Edit|Write and plugin B registers a PostToolUse hook on .*, both fire on every Edit. Order depends on: +Personal-level hooks (~/.claude/settings.json) load first +Project-level hooks (.claude/settings.json) load second +Plugin-level hooks load in plugin install order +Within the same level, alphabetical by plugin name +Most people don't know this. So they install 5 plugins and assume "Claude Code figures it out." It doesn't. +It runs all of them, in the order they happened to load, with no awareness that 3 of them are doing the same job. +The other thing nobody talks about: a PostToolUse hook that modifies a file triggers another PostToolUse event. +This is the #1 cause of the cascade problem. If you have a Prettier hook on Edit|Write and an ESLint hook on Edit|Write, the Prettier write triggers the ESLint hook, which writes again, which triggers Prettier again. Both are using your tokens to run. +The 3 conflicts that destroy 90% of setups +Conflict #1 — Two formatters fighting +The classic. You have Prettier and Biome (or ESLint --fix). Both registered on PostToolUse: Edit|Write. Both rewrite the same file. Each rewrite triggers the other. +How to spot it: look at hook execution count after a single Edit. If you see PostToolUse fired 3+ times in one tool call, you have a cascade. +# Diagnostic: run this in a project after one Claude edit +grep "PostToolUse" ~/.claude/logs/$(ls -t ~/.claude/logs/ | head -1) | wc -l +If the result is more than 2 per Edit, you're in cascade. +What it costs. A clean Edit on a 200-line file costs ~3,200 tokens (read file -> edit -> write). With a 3-fire cascade, the same edit costs ~9,600 tokens. Every formatter run re-tokenizes the modified file as part of the next hook's context. On a 50-edit refactor, that's the difference between $0.40 and $1.20 in API spend, or for Max users, half a day of weekly limit gone to formatting fights. +Conflict #2 — Multiple "code reviewers" +You installed Superpowers (which runs a reviewer subagent). You also installed a separate code reviewer plugin. ECC adds its own code-reviewer.md agent. All three trigger on PR creation or after Edit. +Result: Claude gets three contradictory reviews. It tries to merge them. The merged response is inconsistent. You think "the model is bad today." It isn't. You have three reviewers fighting. +How to spot it: after a code change, ask Claude "which agents reviewed this?". If the answer is more than one, decide which one you actually trust and disable the rest. +Conflict #3 — UserPromptSubmit injection wars +This is the silent killer. UserPromptSubmit hooks let plugins inject context into every prompt you send. Useful for things like "current branch name" or "last commit message." +Some plugins inject a lot of context. ECC injects continuous-learning instincts. claude-mem injects memory summaries. Skill Each prompt now has 8KB of pre-pended context before your actual question. +Result: Claude's response degrades because the signal-to-noise ratio collapsed. Your CLAUDE.md instructions are buried under three layers of plugin chatter. The behavior people blame on "Claude getting dumber" is often this. +Concrete example. I had ECC, claude-mem, and a custom git-context skill all injecting on UserPromptSubmit. My prompts looked clean ("fix the bug in auth.js line 42"). Claude was receiving 6,400 tokens of injection before my question. Average response quality measured against my own CLAUDE.md rules dropped from 78% rule-compliance to 41%. After disabling claude-mem injection (kept its retrieval, killed the auto-inject) compliance went back to 76%. Same model. Same prompts. Different signal to noise. +How to spot it: in Claude Code, run /transcript after a session. If the actual user-prompt-token-count is lower than the total-prompt-token-count by 3x or more, you have heavy injection. Pick which plugins genuinely earn their slot. Disable the rest. +The 3-line fix +Open ~/.claude/settings.json (or your project .claude/settings.json). Add: +{ + "hooks": { + "PostToolUse": [ + { + "matcher": "Edit|Write|MultiEdit", + "hooks": [ + { + "type": "command", + "command": "[ -f .claude/.hook-lock ] && exit 0; touch .claude/.hook-lock; npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\" 2>/dev/null; rm -f .claude/.hook-lock; exit 0" + } + ] + } + ] + } +} +What this does: +Lock file .claude/.hook-lock. First PostToolUse creates it. Any nested PostToolUse triggered by the formatter sees the lock and exits immediately. Cascade dies. +Single formatter path. Pick one (Prettier OR Biome OR ESLint --fix). Pick. One. Don't hedge. +exit 0 always. Never let a formatter failure cascade into Claude retrying the edit. If Prettier fails on a file, that's information for you, not for the agent. +Three lines. The [ -f .claude/.hook-lock ] && exit 0 check is the entire fix for cascades. +Add to .gitignore: +.claude/.hook-lock +Why a lock file (and not a debounce or a timeout) +The obvious alternatives don't work: +Debounce by timestamp. + "Skip if last fire was less than N seconds ago." Fragile. N too short and you lose legitimate edits, too long and cascades still fire. Also depends on clock sync and breaks in CI. +async: true on the hook. + Removes blocking but creates race conditions. Two hooks writing the same file in parallel, last-write-wins, silent corruption. Worse than the cascade. +Hook-level if checks ("only run if file changed since last run"). +Works for one hook but doesn't compose. Plugin authors don't know what other plugins are installed alongside theirs. +Disable hooks by plugin name. + Brittle. Survives until the next plugin install or rename. +The lock file works because it's stateful, single-source-of-truth, and atomic at the filesystem level . The first hook in a chain creates it. Every subsequent fire, whether from the same plugin or a different one, sees the lock and exits. The file is removed at the end of the formatting pass. +Cross plugin, cross tool, no coordination needed. +Auditing your existing setup +Before adding the fix, you need to know what you have. Here's a 30-second audit: +# List all hooks across personal + project levels +cat ~/.claude/settings.json 2>/dev/null | jq '.hooks // {}' +cat .claude/settings.json 2>/dev/null | jq '.hooks // {}' + +# List all installed plugins +claude /plugin list + +# Find duplicate matchers (same event + same matcher = fight) +cat ~/.claude/settings.json .claude/settings.json 2>/dev/null \ + | jq -s '[.[].hooks // {}] | add | to_entries[] | {event: .key, matchers: [.value[].matcher]} | select(.matchers | length > 1)' +If you see two entries with the same event and overlapping matchers, you have a fight. Pick the winner. Delete the loser. Rerun the audit. +For ECC users specifically: npx ecc-agentshield scan will surface most of these conflicts in its audit pass. +When to use Agent Teams instead +Claude Code v2.1.32+ has Agent Teams as an experimental feature (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1). This is the official answer to the multi-agent problem. It requires Opus 4.6 , which means it's significantly more expensive per token than running hooks. But the cost-per-task can be lower because teammates work in parallel and don't pollute each other's context. +Agent Teams give you: +A team lead that coordinates all teammates +Each teammate runs in its own context window (no pollution) +Shared task list for coordination +Direct messaging vs broadcast (cost aware) +This is genuinely the right solution for parallel work: refactoring 3 modules at once, running tests in isolation, code review in parallel. It is not a replacement for hooks. Hooks are deterministic enforcement (always run Prettier on save). Teams are AI-coordinated parallel work (refactor X while reviewing Y). +The trade-off: Teams burn Opus 4.6 tokens at 5x the rate of a Sonnet 4.6 single-session. A 3-teammate refactor that finishes in 12 minutes might cost the same as a 45-minute Sonnet session. Faster, not cheaper. Use the speed when it matters (a customer is waiting, you're trying to ship before EOD), not when it doesn't. +Use both. Hooks for "must always run." Teams for "complex parallel tasks that benefits from speed." +What didn't work +Things I tried before settling on the lock-file fix: +Disabling all hooks. + Fixed the cascade but lost the value of formatters/linters. Not viable for production. +async: true on hooks. + Works for Stop hooks but creates race conditions on PostToolUse. Files get written mid-format. Don't. +Plugin-level disabling via ECC_DISABLED_HOOKS. + Works only if you use ECC, and you still have to know which hooks conflict. Doesn't generalize. +Reducing hooks to one per event. + Clean but you lose features. The lock file gives you both. +Hook ordering manipulation by renaming plugins alphabetically. + Works but fragile. Survives until the next plugin installs. +The lock file approach won because it's plugin-agnostic, survives reinstalls, and handles the cascade root cause directly. +Symptoms that mean you have this problem right now +Run this checklist on your current setup: +Hit Claude Max usage limits more than 2 days before the weekly reset +"Claude got dumber" feeling that started after installing 2-3 plugins +CLAUDE.md instructions being ignored that worked fine 2 weeks ago +Edit operations that take noticeably longer than they used to +Two different "code review" outputs in one response +Conflicting suggestions from agents in the same session +PostToolUse fires more than once for a single Edit +"permission denied" or hook errors appearing in transcript +If you checked 3+, you have agents fighting. Apply the fix. +Full settings.json (copy-paste ready) +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|DROP TABLE|--force|sudo' && { echo '{\"message\":\"Blocked: dangerous command\"}'; exit 2; } || exit 0" + } + ] + } + ], + "PostToolUse": [ + { + "matcher": "Edit|Write|MultiEdit", + "hooks": [ + { + "type": "command", + "command": "[ -f .claude/.hook-lock ] && exit 0; touch .claude/.hook-lock; npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\" 2>/dev/null; rm -f .claude/.hook-lock; exit 0" + } + ] + } + ], + "Stop": [ + { + "hooks": [ + { + "type": "command", + "command": "echo \"$(date): session complete\" >> ~/.claude/work.log", + "async": true + } + ] + } + ] + } +} +This config: blocks dangerous bash, formats every edit exactly once, logs sessions for later analysis. No fights. +The mental model +Stop thinking about Claude Code as one assistant. Start thinking of it as a small distributed system. +Hooks = deterministic infrastructure. Always runs. Doesn't think. +Skills = specialized procedures. Loaded on demand by the model. Think of them as well-documented functions. +Subagents = isolated workers with their own context window. Use for parallel work or context isolation. +Agent Teams (experimental) = coordination layer over subagents. Use for complex parallel features. +CLAUDE.md = the soft contract. Followed about 80% of the time. Use for style and convention, not safety. +The fights happen when you treat all five as the same thing. They're not. Each layer has a role. +For things that must happen every time: hooks (with the lock file). For things that need specialized procedures : skills . For things that need isolated workspace : subagents . For complex parallel work : Agent Teams . +Stop layering 5 hooks for the same job. Pick the right tool. The fighting stops. +One more frame: race conditions, not bad behavior +If you've worked on distributed systems, the cascade pattern is a familiar one: two processes, no shared lock, both writing to the same resource, both triggering each other. The solution there is the same as it is here — a mutex. The lock file is a mutex. +The reason this took so long for the Claude Code ecosystem to figure out: most plugin authors are writing in isolation. They test their plugin alone, on a clean install, and ship. Nobody is responsible for the interaction between plugins. There's no global ordering rule because nobody owns the global. Each plugin assumes it's the only one running on Edit|Write. +Agent Teams is Anthropic's first attempt at a coordination layer. The lock file is what you can do tonight, without waiting for the ecosystem to catch up. Both will exist for a long time: one for "coordinated parallel work," one for "deterministic guarantee no matter who else is in the room." +Closing +The Claude Code ecosystem grew faster than anyone expected. Marketplaces went from 16 official skills in late 2025 to 1.2M+ community skills indexed across marketplaces by April 2026. The plumbing didn't catch up. Most setups installed in the last 6 months have at least one of the conflicts above, and most of them blame the model. +This is the third pattern I've documented in the same family. The first was where your tokens actually go (73% wasted on 9 invisible patterns). The second was the rules that govern what Claude does once the tokens land (Karpathy's 4 + my 8). This one is the layer underneath both: the wiring between the plugins themselves. Each of the three layers has its own kind of failure mode. Most setups have at least one failing. +Your tokens are real money. Your time is real time. Three lines of settings.json and an evening of audit work returns 30%+ of both. +Audit your setup tonight. Add the lock file. Pick one formatter. Run for a week. Check your usage \ No newline at end of file diff --git a/学习笔记/Claude Multi-Agent Systems.md b/学习笔记/Claude Multi-Agent Systems.md new file mode 100644 index 0000000..847562d --- /dev/null +++ b/学习笔记/Claude Multi-Agent Systems.md @@ -0,0 +1,415 @@ +Claude Multi-Agent Systems: The Complete Guide From Zero to Running a 4-Agent Team Alone +Most people think building a multi-agent system requires a computer science degree, a DevOps background, and three weekends of debugging infrastructure. +It does not. +It requires understanding one principle clearly. +A team of specialists always outperforms a generalist working alone. +This is as true for AI agents as it is for human organizations. +When you ask one Claude instance to research, write, review, and distribute content in the same session, you get mediocre output in every category. The context constantly shifts. The quality standards constantly conflict. The model is optimizing for too many things at once. +When you build four specialized agents with distinct roles, clear handoffs, and a master orchestrator coordinating them, you get exceptional output in every category because each agent is doing exactly one thing well. +This guide takes you from zero to running a functional 4-agent team by the end of the weekend. +Why Four Agents and Not One +Before the architecture, the principle. +The number four is not arbitrary. +Four agents represents the minimum viable team structure that covers the full cycle of knowledge work: intake and research, production, quality control, and output and distribution. +Every complex knowledge work task passes through these four phases. +A single agent context-switching between all four phases produces output that is inconsistent in quality, slow in execution, and difficult to debug when something goes wrong. +Four specialized agents produce output that is consistent because each agent has one job, fast because agents work in parallel where the workflow allows, and easy to debug because failures are isolated to the agent where they occur. +The math matters too. +One agent running four phases sequentially takes four times as long as four agents running their phases simultaneously. +For a content operation producing 20 pieces per week, the parallelism difference alone justifies the architecture. +The 4-Agent Architecture +Here is the complete team structure. +Agent 1: The Research AgentRole: Information gathering and synthesis. Input: A topic, a question, or a brief. Output: A structured research brief. Never does: Writing, editing, or publishing. +Agent 2: The Production AgentRole: Turning research briefs into finished content. Input: The Research Agent's structured brief. Output: A complete first draft. Never does: Research, editing, or publishing. +Agent 3: The Quality AgentRole: Evaluating and improving production output. Input: The Production Agent's first draft. Output: Either an approved draft or a specific revision brief. Never does: Research, writing from scratch, or publishing. +Agent 4: The Distribution AgentRole: Formatting and deploying approved content. Input: The Quality Agent's approved draft. Output: Content deployed to the correct platform in the correct format. Never does: Research, writing, or quality assessment. +The OrchestratorRole: Routing tasks between agents, managing the workflow, and handling failures. Input: The initial task. Output: A completed deliverable. Knows everything the other agents are doing. Each agent knows only its own task. +Setting Up Your Environment +Before you build any agent you need three things in place. +Claude Code installed and configured. +If you do not have Claude Code installed, run: +npm install -g @anthropic-ai/claude-code +claude +Follow the authentication flow. Verify the installation worked: +claude --version +A project directory with a master CLAUDE.md. +Create your project directory: +mkdir multi-agent-system +cd multi-agent-system +Create the folder structure your agents will use: +mkdir -p inbox research-briefs drafts approved-content distribution logs +The inbox folder is where tasks enter the system. Research briefs are deposited here after the Research Agent runs. Drafts are deposited here after the Production Agent runs. Approved content is deposited here after the Quality Agent approves. Distribution tracks what has been published. Logs records every agent action for debugging. +The master CLAUDE.md. +Create CLAUDE.md in your project root: +# Multi-Agent System — CLAUDE.md + +## System Overview +This is a 4-agent content production system. +Each agent has one specific role and must not perform functions +outside that role. + +## Agent Roster +- Research Agent: Produces structured research briefs from topics +- Production Agent: Produces first drafts from research briefs +- Quality Agent: Evaluates and approves or returns drafts +- Distribution Agent: Formats and deploys approved content + +## Folder Structure +inbox/ — incoming task files +research-briefs/ — research agent outputs +drafts/ — production agent outputs +approved-content/ — quality agent approvals +distribution/ — deployment records +logs/ — operation logs + +## Shared Standards +- Every output file must be named: YYYY-MM-DD-[type]-[topic].md +- Every agent must log its action to logs/operations.md +- Every agent must read this CLAUDE.md before starting any task +- No agent takes action outside its defined role + +## Quality Bar +Research: Minimum 3 sources cross-referenced. No unsourced claims. +Production: Matches voice profile. Every sentence earns its place. +Quality: Scores 8/10 or above on all criteria before approval. +Distribution: Platform-specific formatting. No generic formatting. + +## Hard Rules +- Never delete files. Archive to a timestamped backup folder. +- Never publish without Quality Agent approval in the file header. +- Log every action before taking it, not after. +- When uncertain: stop and flag for human review. +Building Agent 1: The Research Agent +The Research Agent is the most important agent in your system because the quality of everything downstream depends on the quality of what it produces. +A weak research brief produces weak drafts. A strong research brief produces strong drafts. The Production Agent cannot add insights the Research Agent did not find. +The Research Agent System Prompt +Save this as 05-system/agents/research-agent.md: +# Research Agent + +## Identity +You are a specialist research agent. Your only job is to produce +Research Briefs. You never write content. You never evaluate drafts. +You research and synthesize. + +## Trigger +When called with a topic or brief from the inbox folder. + +## Pre-Task Checklist +1. Read CLAUDE.md for current system context +2. Check research-briefs/ for any existing research on this topic +3. Identify what is already known before searching for new information + +## Research Process +1. Identify the core question the content needs to answer +2. Find the most relevant information from multiple angles +3. Cross-reference at least 3 independent sources for factual claims +4. Identify the insight most people miss on this topic +5. Find the counterintuitive angle that creates genuine interest +6. Locate 3 specific examples, statistics, or stories +7. Identify 3 potential content angles ranked by potential + +## Output Format +Save to: research-briefs/YYYY-MM-DD-research-[topic].md + +CORE INSIGHT: [one sentence — the non-obvious angle] +TARGET AUDIENCE: [specific description] +SUPPORTING EVIDENCE: [3 specific examples with sources] +COUNTERINTUITIVE ANGLE: [what most people get wrong] +KEY DATA: [2-3 specific numbers or quotes] +CONTENT ANGLES: [3 ranked angles with one-sentence descriptions] +GAPS: [what this research could not answer] + +## Quality Standard +If the core insight is something most people already know, +it fails. The insight must be genuinely non-obvious. +Never include a claim you cannot support with a specific source. + +## Logging +Append to logs/operations.md: +[TIMESTAMP] Research Agent: Completed research on [TOPIC]. +Brief saved to research-briefs/[FILENAME]. +Running the Research Agent +To trigger the Research Agent manually: +claude "Read CLAUDE.md and the research-agent.md skill file. +Then read the task file in inbox/[TASK-FILE]. +Run the research process and produce the brief." +To run it as an automated workflow via N8N, the HTTP request body looks like this: +{ + "model": "claude-opus-4-5", + "max_tokens": 4096, + "system": "[CONTENTS OF CLAUDE.md + research-agent.md]", + "messages": [{ + "role": "user", + "content": "Run the research process for this task: [TASK CONTENT]" + }] +} +Building Agent 2: The Production Agent +The Production Agent transforms research briefs into finished content. +The most critical element of this agent is the voice profile. Generic AI content fails because it sounds generic. A precisely configured voice profile produces content that sounds like you wrote it at your best. +Before you write the Production Agent system prompt, collect your 10 best-performing pieces of content. Ask Claude to analyze them and extract your patterns: +Analyze these 10 pieces of content and extract the following: +1. Average sentence length +2. Capitalization patterns (what do you capitalize strategically?) +3. Structural patterns (how do you open, develop, close?) +4. Vocabulary level and specific word choices +5. What you never do (hedges, filler phrases, etc.) +6. How you handle transitions between ideas +7. Your CTA style + +Content samples: [PASTE YOUR 10 BEST PIECES] +Save that analysis. It becomes the voice profile section of your Production Agent. +The Production Agent System Prompt +Save this as 05-system/agents/production-agent.md: +# Production Agent + +## Identity +You are a specialist content production agent. Your only job is to +produce first drafts from research briefs. You never research. +You never evaluate. You produce. + +## Trigger +When a new file appears in research-briefs/ folder. + +## Pre-Task Checklist +1. Read CLAUDE.md for system context and quality standards +2. Read the research brief completely before writing anything +3. Identify the strongest angle from CONTENT ANGLES in the brief + +## Voice Profile +[INSERT YOUR EXTRACTED VOICE PROFILE HERE] + +## Production Process +1. Select the strongest content angle from the research brief +2. Write the opening hook using the voice profile patterns +3. Develop the body using SUPPORTING EVIDENCE from the brief +4. Weave in the COUNTERINTUITIVE ANGLE as the core tension +5. Use KEY DATA as proof points, not as the main argument +6. Close with a CTA that fits the content type + +## Output Format +Save to: drafts/YYYY-MM-DD-draft-[topic].md + +Include at the top of every draft: +--- +SOURCE BRIEF: [filename of research brief used] +CONTENT ANGLE: [which angle was selected and why] +WORD COUNT: [actual word count] +PRODUCTION DATE: [date] +--- + +## Quality Self-Check Before Submitting +- Does every sentence match the voice profile? +- Is the hook strong enough to stop a scroll? +- Is there at least one specific number or example per major point? +- Does the CTA tell the reader exactly what to do? + +If any answer is no, revise before submitting. + +## Logging +Append to logs/operations.md: +[TIMESTAMP] Production Agent: Completed draft for [TOPIC]. +Draft saved to drafts/[FILENAME]. +Building Agent 3: The Quality Agent +The Quality Agent is the gate between production and publication. +Most multi-agent systems skip this agent and wonder why their outputs are inconsistent. +Without a Quality Agent, every piece of content that exits the Production Agent goes directly to distribution regardless of quality. Good days produce good content. Bad days produce bad content. There is no floor. +With a Quality Agent, nothing gets published below a defined quality threshold. The floor is consistent because the gate is consistent. +The Evaluation Rubric +The Quality Agent evaluates every draft on five criteria: +VOICE MATCH (1-10): Does this sound exactly like the configured voice? +HOOK STRENGTH (1-10): Does the first line stop the scroll? +INFORMATION DENSITY (1-10): Does every sentence earn its place? +CTA CLARITY (1-10): Is the call to action specific and compelling? +FORMAT COMPLIANCE (1-10): Does it follow all format requirements? + +Passing threshold: 8 or above on ALL five criteria. + +If any criterion scores below 8: +- State which criterion failed +- State exactly what needs to change +- Return to Production Agent with a specific revision brief +- Do not provide vague feedback + +If all criteria score 8 or above: +- Add APPROVED header to the file +- Move to approved-content/ folder +- Log the approval +The Quality Agent System Prompt +Save this as 05-system/agents/quality-agent.md: +# Quality Agent + +## Identity +You are a specialist quality control agent. Your only job is to +evaluate drafts and either approve them or return them with +specific revision instructions. You never write from scratch. +You never research. You evaluate and direct. + +## Trigger +When a new file appears in drafts/ folder. + +## Evaluation Process +1. Read CLAUDE.md for quality standards and voice profile +2. Read the draft completely without evaluating +3. Read it again with the evaluation rubric active +4. Score each criterion honestly — never round up + +## Scoring Rubric +[INSERT FIVE-CRITERION RUBRIC] + +## Approval Output +If all criteria score 8 or above: +Add to top of file: +--- +QUALITY APPROVED +Approval Date: [DATE] +Scores: Voice [X] | Hook [X] | Density [X] | CTA [X] | Format [X] +--- +Move file to approved-content/ + +## Revision Output +If any criterion scores below 8: +Create a revision brief in drafts/REVISION-[ORIGINAL-FILENAME].md: +--- +REVISION REQUIRED +Failed Criterion: [CRITERION NAME] - Score: [SCORE] +Specific Issue: [EXACT PROBLEM] +Required Change: [EXACT CHANGE NEEDED] +Example of Correct Approach: [SHOW DON'T TELL] +--- + +## Hard Rules +Never approve content that fails any criterion. +Never give vague feedback like "make it more engaging." +Be specific or the Production Agent cannot fix it. + +## Logging +Append to logs/operations.md: +[TIMESTAMP] Quality Agent: [APPROVED/RETURNED] [FILENAME]. +[IF RETURNED: Failed criterion and reason] +Building Agent 4: The Distribution Agent +The Distribution Agent is the final agent in the chain. +Its job is simple but consequential. It takes approved content and formats it correctly for each target platform, then handles the deployment. +Platform-Specific Formatting +Different platforms require genuinely different content formats. +Twitter/X: Maximum 280 characters per tweet. Threads for longer content. Short sentences. Strategic line breaks. Every tweet must stand alone. +LinkedIn: Professional adaptation. Longer sentences acceptable. Narrative structure works. First line must work as a standalone hook. +Newsletter: Full formatting with headers. HTML-compatible. Consistent section structure. Clear subject line. +The Distribution Agent knows all of these formats and applies them automatically based on which platforms are specified in the approved content header. +The Distribution Agent System Prompt +Save this as 05-system/agents/distribution-agent.md: +# Distribution Agent + +## Identity +You are a specialist distribution agent. Your only job is to take +approved content and format and deploy it correctly for each +specified platform. You never write from scratch. You never evaluate. +You format and deploy. + +## Trigger +When a new file appears in approved-content/ folder. + +## Pre-Task Checklist +1. Verify the QUALITY APPROVED header is present +2. Identify the target platforms from the content header +3. Read the platform formatting guidelines for each target + +## Platform Formatting Guidelines +[DEFINE YOUR SPECIFIC FORMAT REQUIREMENTS FOR EACH PLATFORM] + +## Distribution Process +1. Verify quality approval +2. For each target platform: + a. Reformat content to platform specifications + b. Verify formatting meets platform requirements + c. Deploy via configured integration (Typefully, Buffer, etc.) + d. Record the deployment in distribution/[DATE]-log.md +3. Update the original file header with deployment confirmation + +## Output +For each platform: +Create: distribution/YYYY-MM-DD-[platform]-[topic].md +Include: formatted content + deployment confirmation + timestamp + +## Hard Rules +Never distribute content without QUALITY APPROVED header. +Never distribute to a platform without platform-specific formatting. +Always record every deployment in the distribution log. + +## Logging +Append to logs/operations.md: +[TIMESTAMP] Distribution Agent: Deployed [TOPIC] to [PLATFORMS]. +Building the Orchestrator +The Orchestrator is not a fifth agent. +It is the routing logic that connects the four agents into a coherent workflow. +In its simplest form, the Orchestrator is a Claude session that knows the full system and routes tasks between agents. +The Orchestrator System Prompt +# Orchestrator + +## Role +You manage a 4-agent content production system. You receive tasks, +route them to the correct agent, monitor for completion, handle +failures, and ensure the workflow reaches its final output. + +## Workflow +Task received → Research Agent → Production Agent → Quality Agent +→ Distribution Agent → Workflow complete + +## Your Responsibilities +1. Break incoming tasks into the component brief for each agent +2. Monitor each agent's output folder for completion signals +3. Pass the correct output to the next agent in sequence +4. If an agent returns a revision: route back to the correct agent +5. If an agent fails: log the failure and flag for human review +6. Confirm workflow completion when content is distributed + +## Failure Handling +Quality rejection → Return to Production Agent with revision brief +Research gap → Request additional research before production +Distribution failure → Log failure, alert human, do not retry automatically + +## You Never +Skip the Quality Agent under any circumstances. +Approve your own outputs — each agent is evaluated by the next. +Make creative decisions — route and manage only. +Running Your First End-to-End Task +With all four agents configured, here is how to run your first complete task. +Create a task file in your inbox folder: +# Task: [YOUR FIRST TOPIC] + +## Content Type +[Tweet thread / Article / Newsletter section] + +## Target Platforms +[X / LinkedIn / Newsletter] + +## Specific Requirements +[Any specific requirements for this piece] + +## Deadline +[When this needs to be live] +Trigger the Orchestrator: +claude "Read CLAUDE.md. You are the Orchestrator. +A new task has arrived in inbox/[TASK-FILENAME]. +Begin the workflow. Route to Research Agent first." +Watch the output folders. +research-briefs/ gets a file when Research Agent completes. drafts/ gets a file when Production Agent completes. approved-content/ gets a file when Quality Agent approves. distribution/ gets a file when Distribution Agent deploys. logs/operations.md gets an entry at every step. +Your first end-to-end run will take 15 to 30 minutes depending on complexity. +After 10 runs the system will feel natural. +After 50 runs it will feel indispensable. +The Compounding Effect After 30 Days +The 4-agent system does not just produce better output than a single agent. +It produces output that gets better every month because each agent accumulates context about what works. +The Research Agent learns which sources your audience responds to. +The Production Agent learns which angles drive the most engagement. +The Quality Agent learns where the threshold between good and great actually is for your specific voice. +The Distribution Agent learns which platforms your content performs best on. +None of this learning requires you to do anything beyond running the system and updating the shared CLAUDE.md with performance observations once a week. +The system compounds. +One person running a 4-agent team produces the output of a team of four. +With more consistency. +More speed. +And a feedback loop that makes every piece better than the last. +Build the first agent this weekend. +Add one per week. +By week four you have the full team running. +Follow @cyrilXBT for the exact CLAUDE.md templates, agent skill files, and N8N workflows that power this entire system \ No newline at end of file