The Claude Code SOP Behind HexClaw: Design-Driven Development, Testing Feedback, and Multi-Agent Collaboration

How It Started: A Friend Asked About AI Development

A few days ago, an old friend in Beijing contacted me. As a technical lead building an automated AI workflow for his team, he had two questions: how do you reduce hallucinations, and how do you build the workflow?The three threads below are essentially my answer.

My experience was running inside projects rather than organized into presentation material. I asked Claude to assemble those fragments into documentation—the same package linked at the end—and sent it with my custom Skills and commands. Instead of a one-way presentation, my friend created a WeChat technical discussion group. People read, tried things, and asked questions together, giving each question time for a solid answer. That was end-to-end technical sharing in a practical sense: documentation, hands-on work, questions, and answers in one feedback loop.

He also invited a product-manager friend to discuss a product-side Skill system. That friend's PRDs were systematic and detailed. I tried the Skill on a login module and got a set of test cases plus a test report. More detailed PRDs produced better generation. Product-side methodology is that colleague's specialty; I found it useful, but a proper explanation should come from its author.

Organizing the material made me realize I had never systematically documented how I use Claude Code to build a working product. A feature list is easy; a working method is different.

The three threads are design and implementation, a testing feedback loop, and multi-Agent collaboration. I will examine them in order.

This article is the condensed version of that documentation. It does not list twenty-six Claude Code shortcuts. It describes the workflow needed to build a product that runs, can be tested, and can evolve.

The Numbers First

• Approximately 680,000 lines of code: across Go / TypeScript / Vue / Rust, roughly counted from currently Git-tracked files in six repositories
• Six core repositories: toolkit → ai-core → hexagon → hexclaw → hexclaw-desktop / hexagon-ui; see the full dependency chain in the architecture article）
• One person, spare time: normal work during the day; evenings, weekends, and holidays for this ecosystem
• Pair programming with Claude Code: dozens to over a hundred exchanges daily. Claude Code generated most code; I supplied requirements, chose designs, reviewed changes, and performed final acceptance
• Models: Claude Opus 4.5 / 4.6 did the work described above, and within a few months they became previous generations. Whether the newly released 4.7 or a later version, the workflow stays the constant while stronger models raise its ceiling

These figures are not for showing off. Even looking back, I find them slightly absurd.

The unexpected part was that the resulting quality exceeded my own expectations: comprehensive tests, an ADR for every key decision, stricter review than many projects I previously worked on, clear dependency layers, and no circular references.

This did not happen because Claude Code suddenly became powerful in 2026. Many independent developers used it last year with vastly different results. The difference lies in how it is used.

One industry observation: the rapid iterations of Claude Code, Codex, Cursor, and Chinese coding assistants, together with stronger subscription competition, suggest that AI coding has moved from experimentation into the everyday toolchain. A recent joke in technical groups and on Zhihu exaggerates it this way: Traditional hand-written code needs heritage protection soon, before it ends up in a museum.

Reality is less extreme. The Stack Overflow 2025 Developer Survey found that 84% of developers use or plan to use AI tools, but 46% distrust the accuracy of AI output. Adoption is established; trust remains the central question. A more realistic view is that hand-writing everything is becoming specialist work for selected situations, while generated code needs a loop of design, tests, and review to earn trust.

In 2026, the question is how well to use AI coding. Tool adoption does not equal output quality: some Claude Code users build working products, while others stop at demos.

The Three Threads

A terminology check: around 2026, the industry began using Agentic Engineering to distinguish a more disciplined approach from casual Vibe coding.

Vibe coding, Karpathy's term, means letting AI write by feel and accepting that it runs, suitable for toy projects and quick prototypes. Agentic Engineering emphasizes humans orchestrating Agents, setting quality gates, and verifying outputs so generated code enters an engineering feedback loop. Ultimately, AI can write code, but cannot take your engineering responsibility。

This article describes my particular implementation of Agentic Engineering:

① Design and implementation: ask Claude to compare designs before coding, choose one, split it into small stages, then use red–green–refactor where TDD applies.

② Testing feedback loop: should pass and probably OK do not count as completion. Run verification and obtain evidence. High coverage does not imply effective tests.

③ Multi-Agent collaboration: Claude writes, Codex reviews, and humans decide. Cross-review between different models helps prevent one model's blind spots accumulating into failures.

Each thread below includes actual practice: the problem encountered, the solution used, and the corresponding prompts or shell commands.

Thread One: Design and Implementation

What Happens Without Design

When I started with Claude Code five months ago, my first instinct was familiar: implement feature X for me. Claude produced 200 lines immediately, and they ran.

Over time, asking AI to jump straight into code exposed three specific problems:

1. Architecture degrades quietly. Claude follows the most recently seen patterns in its context. As modules accumulate, it mixes styles. The codebase looks as though five people with different habits wrote it, because each conversation starts with a newcomer who does not remember yesterday's rules.

2. Design selection becomes passive. Claude normally supplies one workable design without alternatives. But the value of technical selection lies in comparison: goroutines or channels, REST or WebSocket. Without comparison, the decision has not really been made.

3. The change radius becomes unpredictable. A request to implement a feature may trigger unrelated changes across several files. Their correctness is unknown until you inspect each diff.

The Better Approach: Three Design Steps

I established one firm rule:

complete the design phase before coding.

By default, switch the whole design phase to Plan mode（Shift+Tab). Claude reads without editing and concentrates on analysis and alternatives.

The three steps:

Step 1: Describe the Intended Work Clearly

A request to build X lacks enough context for a precise design. My usual template is:

The instruction not to rush matters. Claude otherwise starts immediately; this makes it expose ambiguities for confirmation before designing.

Step 2: Ask for Two or Three Alternatives

Only after the context is complete should Claude propose designs. Each must be directly comparable:

That last instruction matters: Claude lays out the choices, and you choose. Otherwise it tends to recommend the apparently safest option and let you follow it.

Step 3: Choose and Write an ADR

After choosing, ask Claude to record an Architecture Decision Record:

Three months later, you or a successor can understand the reason immediately. The rejected alternatives remain available too, so switching does not require starting research again.

These three steps are a compact version of the industry's Spec-Driven Development（SDD）. The open-source Spec Kit（github.com/github/spec-kit） on GitHub divides planning into more reviewable stages. For my product work, these three steps provide enough structure.

Implementation: From ADR to Code

A completed design is not a reason to ask Claude to implement everything at once. I use three practices:

Practice 1: Small Stages, One at a Time

Split the ADR's design into independently releasable stages. Each has a manageable diff, independent testing, and low rollback cost. Implementing everything at once produces a diff nobody can review, an unclear rollback point, and wasted work if an early assumption fails.

Let Claude propose the stages, confirm them, and proceed individually:

Practice 2: TDD, Red → Green → Refactor

For a task suited to TDD, use this prompt:

But TDD is not a silver bullet; choose by scenario:

• Suited to TDD: core pure logic / state machines / algorithms / bug fixes / interface contracts
• Less suited to TDD: exploratory work with unclear requirements / frontend interactions difficult to express in unit tests / third-party integration depending on external behavior / one-off scripts

When TDD is unsuitable, run a spike first and add appropriate verification afterward rather than forcing the method.

Practice 3: Refactor Under Test Protection

When changing existing code, follow a strict sequence:

The critical instruction is to test after each step, not after the entire rewrite. Otherwise, a failure gives no clue which step introduced it.

Three design steps and three implementation practices may look slow. In my experience, an extra hour in design saves ten times that during implementation and evolution. Compared options and recorded decisions keep alternatives available and switching costs low. Skipping them leaves every change's radius unpredictable and every problem requiring fresh research.

Thread Two: A Testing Feedback Loop

The Trap in AI-Written Tests

Ask for unit tests and Claude can produce them in thirty seconds. The serious problem is that it may write to cover code rather than verify behavior。

A typical false sense of safety:

Or:

Such tests can yield high coverage while missing real defects. I learned this directly: a project once had over 90% coverage but omitted a key boundary condition, and production failed after release.

The Better Approach: Verification and Completion Checks

Rule 1: Verification-Driven Work（Anthropic The official best practices (code.claude.com/docs/en/best-practices) emphasize this repeatedly:

Giving Claude a way to verify its work has high leverage. Output quality improves greatly when Claude can check itself。

Four ways to supply verification:

(Tests as verification)

(Screenshots as verification)

(Reject an unverified belief that it runs)

(Self-review)

The point is to reject should pass and probably OK. Tests must actually run and provide evidence.

Rule 2: Map Change Types to Verification Depth

Different changes call for different verification depth:

Put this table in the project's CLAUDE.md so Claude consults it when writing tests.

Rule 3: Check Completion

After claiming a fix, use grep to look for remaining instances.

I think it is fixed is not evidence; grep -c results are.

The purpose is to stop an AI's sense of completion replacing evidence. Coverage and case requirements vary by project, but the loop remains: claim completion, search for remnants, and fix omissions.

Automate Checks with Hooks

A manual grep check eventually gets forgotten. Claude Code's Hooks mechanism can run shell checks automatically on specified events, making delegated execution more dependable.

Two particularly useful hooks:

Pre-commit hook — intercept a proposed commit to prevent sensitive-file leakage:

Post-edit hook — run lint / compilation / tests automatically after edits:

Moving checks from something to remember into automatic execution is central to unattended Claude Code operation. My daily environment has six or seven hooks covering sensitive files, lint, compilation, and key tests. Changes cannot enter the repository without passing them.

The Full DevTestOps Workflow Skill

Those three rules are only the common part of the testing loop. I packaged the complete version as a Skill called devtestops. Install it into Claude Code's ~/.claude/skills/ and the pipeline can trigger automatically.

It includes:

• Seven delivery stages: requirements clarification → design and case preparation → baseline quality verification → main-flow verification → specialized and performance checks → testing handoff and regression → release and observation
• Triggers for eight types of specialized verification: E2E / API / permissions and security / concurrency and idempotency / data consistency / asynchronous queues / configuration compatibility / rollback and observability
• Testing-handoff admission baseline: minimum quality requirements calculated by change type

Compared with the table above, the Skill can identify relevant checks automatically during a change, without a reminder each time.

Thread Three: Multi-Agent Collaboration

The Anti-Pattern: One AI Does Everything

Claude is strong; let it design, code, review, and test everything.

It sounds efficient.

In practice, it is an anti-pattern.

Three reasons:

1. A single model has systematic blind spots.

Claude and Codex have different model families, training data, and reasoning preferences.

When Claude reviews its own code, it can miss problems characteristic of its own style。

. Humans have the same weakness; reviewing your own code is difficult.

2. A normal conversational exchange is poorly suited to review.

Review needs adversarial thinking: actively look for problems instead of following the implementation's logic.

But Claude has already reached agreement with you in that conversation and may preserve that agreement even after switching to review mode.

3. One model does not provide cross-validation.

A good review brings two independent perspectives together to expose blind spots.

Two conversations with the same model are not independent perspectives。

The Better Approach: Claude, Codex, and a Human

Make the responsibilities explicit:

There is no need for two terminals. OpenAI provides the codex-plugin-cc（github.com/openai/codex-plugin-cc) plugin on GitHub, which installs inside Claude Code and makes Codex available in the main session.

Install Once：

The collaboration then uses four slash commands. Prerequisites: Node.js 18.18+, and either a signed-in ChatGPT subscription or a configured Codex API key.

Step A: Claude Finishes Writing → /codex:review Codex Reviews

Codex runs independently, without Claude's conversation context. Both models inspect the diff from their own starting points, giving an independent review.

Step B: Claude Responds to Each Review Finding

After the Codex report arrives, stay in the same Claude Code session:

The key phrase is do not agree performatively. Claude tends to be polite; without this instruction, it may accept most findings and undermine adversarial review.

Step C: Codex Finds Testing Blind Spots

This often finds scenarios Claude missed, particularly races and error paths.

Step D: Review Requirements Against the Design

Running code does not imply all requirements are implemented. This final defense catches technically correct code that leaves the product unfinished.

Then ask Codex to perform the same review independently.

Compare the reports:

• Both find it → fix with high priority
• Only one finds it → verify whether it exists
• They contradict → list the disagreement for human decision

For high-priority bugs, use Step B: reproduce red, fix, verify green. For non-bug gaps such as missing requirements, disconnected flows, or non-functional omissions, complete the original design intent. Do not let the final review become a verbal promise to add something. Every finding needs verifiable evidence.

The Complete Flow

The three threads combine into a full cycle:

The first pass is human requirements and context → Claude compares designs and records an ADR → Claude implements with TDD → Codex reviews independently. Findings take the lower loop: Codex identifies missing tests → Claude fixes bugs → both review requirements → human approves release。

The loop between these rows matters: any failed step can return to an earlier one. If Codex finds an unfixed recursive fallback branch, return to TDD, add verification, and fix again.

Practice: Package the SOP as Slash Commands

I packaged this pipeline as custom commands.

One slash command triggers it.

Two core commands:

/review-go — Deep Go Backend Review

/review-fullstack — Full-Stack Review

In addition to /review-go , check frontend/backend contracts, complete business flows, and effects across repositories in the ecosystem.

The Most Valuable Part: Lessons from Failures

The command templates are not the most valuable part of this SOP.

It is the lessons from past failures that become mandatory pipeline checks.

Every bug missed by AI review becomes an anti-pattern added to the pipeline.

One actual example involved a ctx discontinuity. I asked Claude to replace an outer function's context.Background() with a propagated ctx. It made the change, ran tests, and claimed completion.

After a /codex:review review, Codex reported that the outer ctx was fixed, but the fallback branch of in the same file if err != nil still called Background. Two other helpers in the same module also created new contexts with context.Background() .

It was correct. Claude's completion covered only the entry point within its immediate change radius, not the full recursive call chain.

After fixing it, I turned following only the success path while ignoring fallbacks into a grep check in /review-go . Since then, that type of bug has not escaped the checks.

That is the value of recording failures. A single incident is tolerable; repeated incidents of the same kind are not. Turning each into a mandatory check makes Claude and Codex inspect it next time.

Here are checks I actually added during those five months:

1. Reviewing only the modified function, without following its callees — the outer ctx was fixed, but its helper still used context.Background()
2. Following only the success path, ignoring fallback branches — normal context propagation worked, but the fallback after if err != nil still used Background
3. Changing an interface without checking every implementation — dev contained an implementation absent from main, breaking compilation after merge
4. Claiming completion without searching for remnants — context discontinuity was said to be fixed, while several helpers in the same file still used Background
5. Missing the same problem in neighboring functions — one per-call Transport was fixed, while other functions in the file still constructed one per call

The list grows with use. Each entry reduces the chance of missing that defect class again: failures accumulate into mandatory checks.

A Terminology Clarification

In Claude Code discussions, multi-agent often means its built-in subagent mechanism, where multiple instances of one model research in parallel. More broadly, it includes collaboration across models, toolchains, and context windows. Anthropic's official blog provides a frequently quoted result 《How we built our multi-agent research system》 (anthropic.com/engineering/built-multi-agent-research-system): in 2025, an Opus 4 lead with Sonnet 4 subagents outperformed a single Opus 4 by 90.2% on an internal research evaluation. That is a research evaluation, not a code-review evaluation, and cannot be directly extrapolated to software development.

This article's collaboration is cross-model—Claude × Codex—to reduce blind spots from one model.

The two approaches are compatible. For important features I use both: Claude subagents research code in parallel → Claude designs and implements → Codex cross-reviews. A later article will cover built-in subagents specifically.

What AI Cannot Do

After those three threads, three boundaries have become clear to me:

1. Architecture decisions.

Claude can enumerate designs, but a human must choose。

. That decision needs intuition about the business's future direction, for which the AI lacks data.

2. Cross-system consistency judgments.

Claude works well within one repository.

But deciding whether three repositories have sensible interface agreements, or how a change affects the rest of an ecosystem, requires more:

its context window cannot hold that entire picture

. A human must maintain the global map.

3. Product-experience intuition.

Will users like this interaction? Will this error message alarm them? Should this feature be enabled by default?

The AI has no direct user feedback for these questions and can only suggest common practice.

AI amplifies judgment you already have. The judgment itself remains your responsibility.

Does Opus 4.7 Require Changing the SOP?

Claude Opus 4.7（anthropic.com/news/claude-opus-4-7） has just launched, with official claims of improvements in coding, long tasks, and instruction following. A frequent question is whether this SOP must change for 4.7.

My answer: keep the backbone, but rerun regression checks on prompts, review gates, and the test harness。

. Upgrading a model does not invalidate the need for design, tests, or cross-review; those are workflow decisions. But stronger capabilities can change whether an old prompt and its verification thresholds remain appropriate:

• Prompt wording: ambiguous instructions tolerated by older versions may be followed more literally by 4.7, requiring more precise scope and output formats
• Review gates: if your /review-go strictness was tuned to 4.6 behavior, recalibrate noise versus real findings after upgrading
• Test-harness expectations: cases previously treated tolerantly because they usually failed may now pass reliably, allowing appropriately stricter expectations

I am rerunning the SOP with 4.7, focusing on Plan-mode architecture analysis, ingesting a repository in long context, and adversarial cross-review. A separate article will follow once there are results and cases.

(This section reflects April 2026; details will evolve with subsequent versions.)

Where to Get the SOP

This SOP grew out of building HexClaw rather than being written as a standalone guide.

Now that it is organized, I have published the complete package on GitHub. It is a workflow you can put into a project and try:

• Four practical guides: user guide / prompt collection / extension list / design, testing feedback, and multi-Agent collaboration
• Seven copyable Claude Code command templates with supporting data templates：/review-go、/review-fullstack、/apple-design、/test-dev、/adr-new and others, plus runtime reference data such as data/api-test-cases.md
• Two CLAUDE.md templates: global user preferences (~/.claude/CLAUDE.md) and a project-level override (at the project root, CLAUDE.md）
• A Hooks collection: three ready-to-use scripts for sensitive-file interception, post-edit linting, and pre-completion tests, plus a settings.json configuration sample
• The Complete DevTestOps Skill: seven delivery stages and triggers for eight types of specialized checks (~/.claude/skills/devtestops/）

Everything is in the hexclaw-desktop desktop repository, under docs/claude-code-practices/ :

GitHub：github.com/hexagon-codes/hexclaw-desktop

Clone it and try it directly. I recommend starting with a real project and running /review-go or /review-fullstack once. See the first findings before deciding whether to adopt the SOP in your team.

The repository also contains the product built with this SOP:

HexClaw, a local, open-source desktop AI Agent application whose data stays on your machine (five-minute getting-started guide）。

If you found this useful, visit github.com/hexagon-codes and consider starring the six core repositories: toolkit / ai-core / hexagon / hexclaw / hexclaw-desktop / hexagon-ui. The ecosystem is open source, so explore whichever layer interests you. The commands, Skills, Hooks, and failure lessons will continue evolving in hexclaw-desktop/docs/claude-code-practices/ . Contributions of stronger checks through issues and PRs are welcome.

HexClaw
Deploy locally or in the cloud · Control your data · Free and open-source software
Website: hexclaw.net  |  GitHub: hexagon-codes
Weibo: @HexClaw  |  X: @hexclawapp
Email: [email protected]