Split chat work from repo work
Thinking, artifacts, edits, and proof
After this, you'll be able to tell a chat tool what to produce and tell a code agent what to change without mixing the two jobs.
Before you start
Complete Pick the tool from the work first.
The idea
A chat output is not a repo brief until you convert it.
- "Chat output"
- "Source facts"
- "Approved decisions"
- "Repo brief"
- "Proof and stop rule"
The split: chat tools can produce plans, source summaries, critique notes, tables, specs, and artifacts. Code agents need a different shape: files, target behavior, constraints, commands, review steps, and stop rules.
The split protects both tools. Chat can explore options, compare sources, and shape the idea without touching the repo. The code agent can inspect the current app and make the smallest real change without inheriting every brainstorm turn.
A repo brief is the short packet a code agent reads before it changes files. A good split has two documents. The chat document explains the user need, source facts, decisions, and open questions.
The repo brief names the route, files to inspect, behavior to change, proof commands, and what not to touch.
The failure: pasting a long chat into Codex and saying "build this."
Worked example: the chat output says the pricing page feels vague. The repo brief says "update only the pricing hero, start in src/app/pricing, preserve checkout code, run npm run build, and stop if a plan name changes." That turns a broad opinion into one code task.
The useful version says: "Use this short repo brief. Inspect these files first. Preserve auth and billing. Run proof commands, then stop if the change needs a database update."
Try it (11 min)
Watch out for
- Treating the full chat transcript as proof when it includes unverified claims.
- Putting brainstorming alternatives into the code task.
- Leaving the file boundary as unknown after the agent has inspected the repo.
- Asking the code agent to decide product strategy while editing files.
Paste this into Claude
Turn this chat output into a repo brief: Chat output: [paste a plan, spec, or critique] Repo or route: [known path, route, or unknown] Behavior to change: [one visible outcome] Do not touch: [files, auth, billing, data, or none] Proof: [commands, local page, screenshot, review, or unknown] Return: 1. A five-line repo brief. 2. A source list from the chat output. 3. A stop rule. 4. The items that should stay in chat, not in the repo task.
What a good response looks like
Repo brief: Update the pricing page hero to match the approved messaging. Start in src/app/pricing and shared marketing components. Preserve checkout and account code. Run npm run build and inspect /pricing desktop and mobile. Stop if the copy change requires a new plan name or billing field.
What good looks like
- The repo brief names one behavior change
- It includes source facts from the chat output
- It names the first files or discovery area
- It includes proof and a stop rule
When this breaks
- Breaks when the code agent receives ideas but no target behavior.
- Breaks when the chat tool made a product assumption that nobody approved.
AI can help with this
Use the tool you chose to help you you can tell a chat tool what to produce and tell a code agent what to change without mixing the two jobs. Start with the exercise prompt and your real input. Ask for one draft, then check it against this proof: The repo brief names one behavior change. Accept only the version you can verify yourself.
You can now
You can separate decisions from brainstorm notes
- You can name the code-facing behavior
- You can keep repo instructions short
- You can stop a code agent before it invents product rules
Key takeaways
Chat output becomes useful repo work only after you rewrite it as behavior, files, proof, and boundaries.
- Chat tools shape the idea.
- Code agents change files.
- A handoff should be shorter than the transcript.
- Proof belongs in the repo brief before edits start.
Go deeper