My Claude Code workflow for client projects runs in a fixed order: a spec with acceptance tests, rules files the agents follow, a plan before each edit, one task per branch or worktree, hooks that format and test every change, a second-agent review and my own review of every diff. Staging, an acceptance checklist and a handover of the rules files close the project.
What does a Claude Code workflow for client projects look like?
It looks like ordinary software delivery with the typing handed to agents and every quality gate kept. Anthropic's Claude Code best practices cover the tool; this guide covers client delivery:
- Write the spec and the acceptance tests.
- Write the repository rules in
CLAUDE.mdandAGENTS.md. - Plan each task before any file changes.
- Give each task its own branch or worktree.
- Let hooks run the formatter and tests.
- Have a reviewer subagent, and Codex for risky changes, check the diff.
- Connect tools through MCP with read-only or test-only access.
- Read every diff myself.
- Run the client's acceptance checklist on staging.
- Hand over the code with the rules files.
Why do the spec and acceptance tests come before the first prompt?
Because an agent stops when the work looks done, and without a test, "looks done" is the only signal it has. The best-practices page puts it in one line: "If you can't verify it, don't ship it."
The spec names the users, screens, data model, roles and what is out of scope. Each requirement becomes a plain-language acceptance line, such as "a sales user cannot open another team's deal", and then a failing Pest feature test. The client approves the lines; agents write code until the tests pass. For larger features Claude interviews me about edge cases and writes a spec file, as the same page suggests.
What goes in CLAUDE.md and AGENTS.md on a client repository?
Only what an agent cannot learn from the code: commands, architecture rules, forbidden actions and what "done" means. Claude Code reads CLAUDE.md at the start of every session; Codex reads AGENTS.md before doing any work, per its AGENTS.md page. Claude Code's memory documentation says Claude reads AGENTS.md by default only when there is no CLAUDE.md, so I keep shared rules in AGENTS.md and import it with @AGENTS.md. /init drafts a first version; the docs suggest under 200 lines per file. A generic Laravel skeleton:
# CLAUDE.md
@AGENTS.md
- Use plan mode for any change under app/Billing or database/migrations.
# AGENTS.md (shared by Claude Code and Codex)
## Commands
- Tests: php artisan test
- Format changed files: ./vendor/bin/pint --dirty
- Dependency check: composer audit
## Architecture
- Business rules live in app/Actions; controllers stay thin.
- Every permission check goes through a Policy class.
- Money is integer minor units plus a currency code.
- Schema changes are new migrations; never edit one that has run.
## Never
- Read or edit .env; add new keys to .env.example.
- Run migrate:fresh, db:wipe or anything against a non-local database.
- Add a package without asking; name its license.
## Done means
- A Pest feature test covers the change and all tests pass.
- The acceptance line in docs/spec.md is quoted with its test.
These files are advice, not enforcement: the memory page points to hooks for anything that must be blocked every time.
How do plan mode and worktrees keep agent tasks small?
Plan mode separates reading from writing, and worktrees separate one task's files from another's. I press Shift+Tab until the status bar shows plan mode, or start with claude --permission-mode plan. Claude reads the code and proposes a plan without editing source files, and Ctrl+G opens it in my editor for corrections. For trivial edits the docs advise: "If you could describe the diff in one sentence, skip the plan."
Each approved task then runs in isolation. claude --worktree deal-stages creates a checkout under .claude/worktrees/deal-stages/ on a new branch, worktree-deal-stages, as the worktrees page describes, so parallel sessions never edit the same files. Codex gets its own checkout from git worktree add. One task per pull request keeps each diff readable.
Which checks run automatically on every change?
Formatting after every edit and the tests before Claude ends its turn, both through hooks, which the best-practices page calls deterministic where CLAUDE.md is advisory. They live in .claude/settings.json, which can be committed:
- A
PostToolUsehook with the matcherEdit|Writeruns./vendor/bin/pint --dirtyafter each file change. - A
Stophook runsphp artisan testand blocks the turn from ending while tests fail, so Claude keeps fixing instead of reporting success. - A
PreToolUsehook rejects commands such asmigrate:fresh. Per the hooks reference, exiting with code 2 blocks the tool call.
How do you review AI-written code before it merges?
In three passes, and the last one is mine. First, a reviewer in a fresh context, so it is not grading its own work. Claude Code subagents are Markdown files in .claude/agents/; my reviewer's tools line lists only Read, Grep, Glob, so it cannot edit. It checks the diff against the spec and flags only gaps that affect correctness, because the docs warn that a reviewer asked to find gaps will usually report some. The bundled /code-review skill adds a bug check.
Second, when a change touches money, permissions or data, Codex reviews the branch. Its /review command reports prioritized findings without changing the working tree.
Third, I read every line. If I cannot explain a line, it does not merge; the task goes back with exact instructions, or I write it myself.
Should an agent connect to the client's database or tools through MCP?
Only to copies, with the narrowest access that answers the question. The MCP page advises a read-only database user so the agent's queries cannot change data. My servers point at local or staging databases, never production, and at documentation or tickets with read access. Project servers go in .mcp.json, which Claude Code asks you to approve in an interactive session. The same page warns that servers fetching outside content carry prompt injection risk, so the list stays short and trusted.
What does the agent do, and what do I always do myself?
The agent writes and checks; I decide and answer for the result.
| Task | What I let the agent do | What I always do myself |
|---|---|---|
| Spec | Interview me, draft acceptance lines, list edge cases | Agree scope and priorities with the client |
| Data model | Draft migrations, models and factories | Decide tables, keys, money fields and what must never be deleted |
| Features | Write controllers, views, jobs and Pest tests in a worktree | Approve the plan and read the full diff |
| Permissions | Write Policy classes and a test per role | Define who may see, export and delete what |
| Payments and webhooks | Write handlers and sandbox tests | Verify signature checks, repeat-safe handling and the switch to live keys |
| Dependencies | Propose a package and run composer audit | Check the license, upkeep and whether we need it |
| Data import | Write the mapping and a rejected-rows report on sample data | Reconcile counts and totals with the client |
| Deployment | Draft deployment notes and scripts | Run production deploys and hold the production keys |
Which guardrails protect client code, secrets and data?
Six rules, set before the first task:
- Secrets never go in prompts. No passwords, keys or customer records in prompts or the repository. A deny rule such as
Read(./.env)stops Claude's file tools from reading the env file, and the permissions page evaluates deny rules before ask and allow. - Least privilege. Allow rules cover routine commands such as the test runner; ask rules force a prompt for risky ones. Bypass mode stays off, since the docs reserve it for isolated containers or VMs.
- Approval for destructive commands. Deleting data, force-pushing or touching a server needs my yes. Bash rules match command text and are not a security boundary, the docs note, so agents never hold production credentials.
- Dependency checks. New packages are proposed, not installed, and
composer auditruns before merge. - License checks. Each new package's license is named in the pull request; code of unclear origin is rejected.
- Data never from production. Agents get factories, seeders and anonymized samples.
How do staging, acceptance and handover work?
The client tests on staging, signs off the checklist and receives a repository their team can keep running with AI. Merged work deploys to a staging copy with test data and sandbox payment keys, as in how I work, and any failed acceptance line becomes a new small task. At launch I hand over the repository with CLAUDE.md, AGENTS.md, .claude/settings.json with its hooks and permission rules, the reviewer in .claude/agents/ and an .mcp.json without credentials, plus deployment notes. Their next developer inherits the rules my agents followed. Two weeks of support cover defects in the delivered scope.
How much faster is a Claude Code workflow on a real project?
Much faster on code, and no faster on decisions. In my own work, a project I planned as a six-month build before AI agents now ships in about 7 days when it builds on my existing code, and a roadmap I once quoted as a year takes about 15 days. That comes from 13+ years of tested base code, parallel agents, automated tests and my review of every change. It does not shorten scope decisions, outside approvals such as payment provider checks, messy data or app store review. The custom CRM in 7 days is this workflow applied to a fixed scope.
When should you not use this workflow?
When its gates cost more than the work they protect, or when:
- the project is a throwaway demo;
- the codebase has no tests yet, so tests around the parts you will change come first;
- a contract forbids sending code to outside AI services, unless the client agrees in writing;
- you expect it to replace a regulated system's own audits or to make an unclear scope clear.
If you are choosing between the two agents, read Claude Code vs Codex for building a SaaS. For WHMCS work, my guide to AI coding assistants on large WHMCS module projects covers what never to paste and what to test. To have a project built this way, see hire a Claude Code developer.
Last reviewed 15 October 2026. Disclosure: I sell AI-assisted development as a Claude Code developer, a 7-day custom CRM and a monthly developer retainer, so I am not neutral. I am not affiliated with, certified by or endorsed by Anthropic or OpenAI. Tool details come from code.claude.com/docs and learn.chatgpt.com/docs as read on that date. I am also CTO at ElySpace and founder of MagizAI.
