Claude Code 复杂任务分解与多文件协作技巧

---

Experience: 复杂任务分解与多文件协作 – My hard-earned lessons trying (and failing) to use Claude Code on a real project

I spent last month trying to get Claude Code to refactor a legacy monolith into a service-oriented architecture.

"Hey AI, refactor the user module into a clean architecture."

Within 20 minutes, it had moved half my imports into a directory called ultra_clean_architecture/, deleted three perfectly good repository files because they "looked redundant," and rewritten my database migration class to use a completely different library “because it was cleaner.” I spent the next 4 hours unborking git.

Turns out the problem isn't the AI. It's us giving it the wrong job description.

The "Single Prompt" is a Lie

Everyone on Twitter shows Claude writing an entire Next.js app from a single "make me a SaaS" prompt. For a greenfield to-do list? Sure. For a production codebase with 15 years of edge cases? Get out of here.

I tested this scientifically on my team’s 50k LOC backend.

• **Monolithic Prompt:** "Refactor the billing module into a strategy pattern."
• *Result:* 3 hallucinated files, 2 deleted utility functions, 1 broken import chain. Rollback required.

• **Decomposed Prompting (my current method):**
• Prompt 1: "You are a planner. Analyze `src/billing/`. Output a plan with file names and responsibilities. Do not write code."
• Prompt 2: "Implement the interface `BillingStrategy` in `src/billing/strategies/interface.ts`. Only write the interface."
• Prompt 3: "Implement the concrete `CreditCardStrategy` class. Do not touch anything else."
• *Result:* 0 regressions, 100% clean merge. Took me slightly longer in prompt time, saved me hours of debugging.

Data point #1: Breaking a big refactor into 8 small prompts (under 1500 tokens each) reduced the "spontaneous rewrite" bug by about 70% compared to 1 massive prompt (8k+ tokens). The LLM wants to show off. Smaller scopes keep it humble.

The Manifest File Trick (Multi-File Collaboration)

The worst thing Claude Code does when editing multiple files is "scope creep." It sees a function in services/user.ts and decides it should move it to helpers/user.ts because “it makes more sense architecturally.” Mid-task. Without asking.

The fix? A strict ARCHITECTURE.md / CLAUDE.md file that reads like a contract.

**CLAUDE.md (excerpt)**

- `src/controllers/` handles HTTP request/response. NO business logic.

- `src/services/` contains business logic. CAN call repositories.

- `src/repositories/` contains database queries. CANNOT call controllers.

- `migrations/` and `config/` are EXEMPT from editing unless explicitly allowed.

I prepend every session with:

Read `CLAUDE.md` and `ARCHITECTURE.md`. If a change requires modifying a file that violates these rules, explain the conflict and STOP. Do not auto-edit.

Data point #2: Using a hard-coded manifest file cut cross-file hallucination rates (AI inventing relationships between files that didn't exist) by roughly 60%. It stopped trying to be an architect and started being a good implementer.

The "Poison Pill" Guardrails

This is purely from trauma. I had a session where Claude decided to "optimize" our package.json scripts by removing a "redundant" deployment hook. We pushed to staging. Staging exploded.

Now every non-trivial session starts with a "Don’t Touch" list.

**CRITICAL BOUNDARIES:**

- Never modify `db/migrations/`, `package.json`, `Makefile`, or `.github/`.

- Never delete code comments that contain "DO NOT REMOVE" or "LEGACY".

- If you must change a file in a boundary, you may ONLY output the file path and reasoning to the console. Do not write it to disk.

Data point #3: Adding explicit negative constraints (do not touch X, Y, Z) cut critical production bugs from AI-generated code by about 80% in our sprint. The AI loves to clean things. Sometimes "cleaning" is just nuking technical debt you specifically rely on.

The Cadence Trick

I changed my workflow from "let it cook for 10 minutes" to "one file, one confirmation."

• Prompt -> AI writes file -> I review diff -> Approve -> Next prompt.

It sounds slow, but it isn't. Because the AI isn't sitting there generating garbage for 10 minutes and hiding it in 6 files. It takes 30 seconds per iteration. You can do 10 iterations in 5 minutes.

TL;DR

• Stop asking Claude Code to "refactor the whole module." It can't. Decompose the task into 5–10 explicit files/responsibilities.
• Write a strict `CLAUDE.md` or `ARCHITECTURE.md` that defines file boundary rules. Enforce it in your prompt.
• Use "don't touch" list for sensitive directories (migrations, configs, CI/CD).
• Keep prompt tokens under 2k. Force single-file or highly specific multi-file edits.
• Confirm every step. The "one file, one confirmation" cadence is your safety net.

I still think these tools are incredible, but the hype is doing everyone a disservice. The secret isn't prompt engineering. It's task engineering. You are the architect. Let the AI be the really fast, slightly chaotic intern that needs explicit permission to touch the good china.

Anyone else get burned by a "spontaneous improvement"? Or found better strategies for keeping these things on the rails in a big codebase?

Edit: Thanks for the awards and the DMs. A few people asked for my exact prompt preamble. I'll throw it in a gist tomorrow and link it. Also, 100% agree with the comment that this is basically just "sounding like a senior dev managing a junior dev" – which is exactly the right mental model.

#claucode #aiassistant #refactoring #seniordev #devtools #programming