1. Start with a bounded outcome
“Fix duplicate order notifications” leaves too many choices to an agent. Name the failing behavior, affected surface, intended outcome, and boundaries instead.
A webhook can be delivered twice and produce two order-paid notifications. Trace the event ID from the receiver to the notification job, identify the existing tests, and propose the smallest correction. Do not edit, commit, push, or deploy yet.
This gives Claude Code a question it can investigate. The Claude Code overview describes a tool that can read code, edit files, run commands, and connect to development tools. Those abilities make broad requests more dangerous, not less. Ask it to show which files and tests support its conclusion before it changes anything.
2. Keep project context in CLAUDE.md, but keep it practical
CLAUDE.md is a good home for facts a new contributor needs repeatedly: how to run the app and tests, architectural boundaries, conventions, and commands that should not be guessed.
Keep it concrete. “Use the repository’s existing error pattern in src/errors/” is useful. “Write beautiful, scalable code” is not. Put detailed rules next to the code they govern when that makes the scope clearer, rather than making one enormous root file.
CLAUDE.md is context, not access control. It can tell Claude Code not to deploy. It cannot prevent deployment when the active permissions and credentials allow it. Protect the action itself with the right permission rules, credential scope, and environment.
3. Plan before an uncertain or multi-file change
For work that crosses components, services, or data models, use plan mode before editing. It gives you a chance to check whether Claude Code found the right code path, understood the migration or compatibility risk, and chose a test that can fail for the original bug.
Review a plan against four questions:
- What behavior is changing, and what must stay unchanged?
- Which files prove that this is the active path rather than a dead or similar-looking one?
- What is the smallest safe change?
- Which test or manual check would fail before the change and pass afterward?
Plan mode is not bureaucracy for a one-line spelling correction. It is cheap insurance when a quick edit could quietly change billing, authentication, data handling, or customer behavior.
4. Treat permissions as part of the design
Claude Code’s permission documentation distinguishes Allow, Ask, and Deny rules, as well as permission modes. The mode matters: Manual, accept-edits, plan, and Auto do not ask for the same actions in the same way. On supported Pro, Max, and Team sessions, Auto can be the built-in starting mode.
Before starting work, check /permissions and the current mode. Then match the access to the task:
- An investigation needs reading and perhaps tests, not deployment credentials.
- A narrow implementation needs only the repository and commands it actually uses.
- A production operation needs a separately authorized path, with an accountable owner.
Do not treat a prompt saying “draft only” as a security boundary. It is a request. A correctly scoped credential and an explicit Deny rule are controls.
5. Use a branch for history and a worktree for a separate checkout
Ask Claude Code to name the files it intends to edit and explain why each one is needed. Read the resulting diff as if it came from a new teammate: look for unrelated cleanup, changed defaults, broad dependency upgrades, deleted behavior, and tests that only confirm the new implementation.
A branch gives the change its own line of Git history. A worktree gives it a separate checkout on disk, which is useful when two tasks need different files checked out at the same time. Neither one isolates a shared database, a cloud account, a queue, or a production API. Keep those credentials and targets out of an exploratory task unless they are actually needed and separately authorized.
The practical benefit is review: you can inspect a focused diff and decide whether it is ready to merge. It is not proof of correctness and it is not a fence around external services.
6. Test the failure, the edge, and the boundary
Every change needs evidence that matches its risk. Start with the failure reported, then add the closest edge case and a boundary that must not change.
For a notification service that may receive the same webhook more than once, the cases might be:
- The first fictional
order.paidwebhook creates one notification. - A second delivery with the same event ID does not create a second notification.
- A different event ID for the same order follows the product’s documented business rule rather than being silently discarded.
Run the focused automated test, then the wider check appropriate to the affected code. Read failures rather than asking the agent to “make tests pass” blindly. For UI, permissions, or deployment-adjacent work, add a manual check that observes the actual user-facing result.
A passing command is evidence, not a release decision. Commit, merge, deploy, and monitor are separate decisions with their own owners.
7. Split long work into focused sessions, subagents, and guarded automation
Long conversations accumulate stale assumptions. When the job changes, start a clean conversation with /clear and restate the outcome, relevant files, and acceptance checks. Do not carry a long debugging thread into an unrelated migration just because the context is already open.
For an independent question, use a subagent with a tight job: for example, “find all event-idempotency tests and report their gaps; do not edit.” Subagents help preserve focus, but they still need their own tool and permission limits.
When a procedure repeats, write it as a skill. A narrow SKILL.md can specify the job, required checks, output format, and stopping point. For hard checks, use hooks deliberately: a hook can run a command at a lifecycle event, but it must be tested for the exact event, paths, exit behavior, and failure handling you expect.
For unattended or CI work, use programmatic mode only after choosing its context and credentials. claude -p --bare deliberately skips project discovery, including hooks, skills, MCP servers, auto memory, and CLAUDE.md; it also needs explicit provider credentials rather than a subscription login. That can make a small scripted task more reproducible, but it also means a normal project guardrail will not run unless you provide it another way.
Skills, subagents, hooks, and headless runs standardize a process. They do not grant access, prove a result, or remove the need for human approval on consequential work.
eesel CLI: test the support handoff after a duplicate-event fix
Sometimes a code investigation changes what support should tell customers. After a developer has verified a duplicate-event fix, the support rule might be: “Route payment questions to an authorized person for verification. Do not claim a duplicate charge from a duplicate notification alone.” That should become an owner-approved support note, not an implicit update to a customer-facing agent.
eesel’s CLI lets a support owner, developer, script, or coding agent inspect the same teammate and workspace as the dashboard. It uses JSON output, supports an explicit --agent target, and needs Node.js 18.17 or newer when run with npx.
First identify the authorized test target. The owner, not the coding agent, chooses a non-production teammate and approves the paid chat test:
npx @eesel/cli login
npx @eesel/cli whoami
npx @eesel/cli agents
SUPPORT_TEST_AGENT="REPLACE_WITH_OWNER_APPROVED_NONPRODUCTION_AGENT"
npx @eesel/cli status --agent "$SUPPORT_TEST_AGENT"
npx @eesel/cli instructions --agent "$SUPPORT_TEST_AGENT"
npx @eesel/cli integrations --agent "$SUPPORT_TEST_AGENT"
The shell variable is deliberately explicit. It prevents a script from silently using a saved default teammate. Confirm the signed-in workspace, agent, instructions, and connected sources before testing. Then set consequential actions to Disabled in the teammate’s Actions settings. A new conversation or a “do not send” prompt does not enforce that boundary.
Give the test only the owner-approved fictional note, rather than assuming the repository or a Claude Code conversation has become support knowledge:
npx @eesel/cli new --name "Duplicate event guidance review" --agent "$SUPPORT_TEST_AGENT"
npx @eesel/cli chat "Fictional approved guidance: a duplicate order notification is not proof of a duplicate charge. Route payment questions to an authorized person for verification; do not promise a refund or correction. No order-record data or lookup tool is supplied for this test. Never claim a record was checked. A customer says they received two order-paid emails. Draft the reply from this note only; do not send or change anything." --agent "$SUPPORT_TEST_AGENT"
Chat is billed work; setup and observation are free. The expected result is a proposed draft that does not assert a duplicate charge or claim it checked a record. In separate fresh conversations, repeat the approved note and supply either fictional evidence of a confirmed double charge or an unclear payment state. Both should preserve the handoff to an authorized person rather than promise a refund or invent a lookup. These response-only tests do not verify a payment integration. Record the reply, source conditions, and failures. These are test cases to run, not results from a test we performed.
If the owner later wants to change instructions or knowledge, inspect the exact write first and use --dry-run where the command supports it. Read the updated state back, rerun the cases, and make a separate decision for any live pilot. The same teammate remains visible in the dashboard, where the support owner can review the change and any held approvals.
The point of these Claude Code practices is to make judgment easier: show what is changing, what access the agent has, why the diff is narrow, and what the test actually proved. Use an approved support process to translate a verified finding into customer guidance.
The image shows an example workspace, not the outcome of the fictional duplicate-event test.
Try eesel for a non-production support evaluation.
Frequently Asked Questions
What is the most important Claude Code best practice?
Start with a bounded outcome and the evidence needed to accept it. A precise request, a plan, a reviewed diff, and a relevant test are more reliable than a large prompt asking the agent to “fix everything.”
Does CLAUDE.md enforce security rules?
No. CLAUDE.md gives Claude Code useful project context and instructions. Use permissions, credential scope, sandboxing, and the downstream system’s authorization to enforce access.
Should I always use Claude Code plan mode?
Use plan mode when the change is uncertain, spans several files, or could affect production behavior. For a small, understood edit, a short request plus normal diff and test review may be enough.
Does Claude Code always ask before changing files?
No. Its behavior depends on the active permission mode and rules. Auto and accept-edits modes can approve some work differently from Manual mode, so inspect the mode and permission rules before starting.
How should I test a Claude Code change?
Test the reported failure and the nearest risky edge case, not only a happy path. Review the diff, run the relevant automated checks, and verify the user-visible behavior where practical.
