To use Claude Code reliably, start in the intended repository, define one specific change and how you will verify it, grant only the access the task needs, then inspect the diff and run relevant checks before accepting the work. For a bug fix, identify the failing behavior, name the regression test to add, and instruct Claude Code not to read secrets or change unrelated API behavior.
Claude Code is a command-line coding agent that can inspect and edit repository files and use command-line tools, subject to your configuration and permissions. This guide covers a supervised local repository workflow. It does not promise unattended delivery to production.
The useful mental model is not “ask for code and accept the answer.” It is “give a bounded task, observe the agent’s work, and make a human decision from recorded evidence.”
How to use Claude Code reliably
Use Claude Code as a supervised contributor: specify the task, bound its access, and verify the evidence before accepting its changes.
Anthropic introduced Claude Code on February 24, 2025, as a limited research preview for delegating engineering tasks from the terminal. Its launch announcement describes capabilities including code inspection, file editing, test execution, and GitHub workflows. What it can do in a particular session depends on the current product, your setup, repository permissions, and the commands you allow.
Specify the work, limit access to what it needs, and verify the result before it leaves your working tree.
Set up Claude Code in the right repository
Use Anthropic’s current installation and authentication instructions. Installation methods, supported environments, and authentication options can change, so avoid placing an old command in a permanent team guide. Once Claude Code is installed and authenticated for the relevant account or deployment:
- Open a terminal and change into the intended project directory.
- Check the working tree before requesting edits. For example, run
git status --shortand record any existing changes that must be preserved. - Identify the repository’s actual test, build, and lint commands from current documentation or configuration. Do not ask the agent to guess them.
- Start a session in that directory and state whether you want inspection only or are ready for proposed edits.
A repository-level CLAUDE.md can contain concise standing instructions such as project conventions, relevant paths, and verified test commands. Keep it maintained. An obsolete command or outdated rule can steer an otherwise capable session in the wrong direction. Anthropic’s settings documentation explains repository instructions and configurable permissions.
For an unfamiliar repository, begin with read access and inspection. Before allowing edits, confirm the current branch, expected working-tree state, and directories that contain credentials, deployment configuration, generated files, or customer data.
Write a task contract before asking for code
A useful request names the problem, expected behavior, scope, constraints, acceptance criteria, and checks. Include the authoritative requirement or decision when one exists. Prompt context is useful, but it should not replace the current source document. If requirements conflict or a product decision is missing, ask the owner to resolve it before implementation.
For a bug spanning more than a trivial edit, ask Claude Code to reproduce or inspect the relevant behavior and propose a focused plan before making changes. A practical contract can look like this:
Task ID: ENG-482
Repository and branch: payments-service, fix/retry-timeout
Problem: A retry with an expired token returns an unhandled error.
Reproduction: [exact command, test, or request that currently fails]
Expected behavior: Return the documented error response.
Scope: [package, files, or subsystem]
Acceptance criteria:
- Add a regression test for the expired-token path.
- Preserve public behavior outside this case.
Constraints:
- Do not read or modify .env files or production credentials.
- Do not change unrelated API behavior.
Checks: [repository-documented command for the affected package]
First inspect the relevant code and explain the likely cause.
Propose a focused plan before editing. Report assumptions or
missing decisions instead of inventing requirements.For a small, well-understood change, the plan can be brief. For a cross-file refactor, security-sensitive change, migration, or behavior change with several acceptance criteria, make the plan an explicit approval gate. Claude Code documents plan mode and configurable permission modes. Check the current CLI reference for version-sensitive flags and behavior.
Run a bounded coding loop
Permissions control what Claude Code can read, edit, and run. For an unfamiliar repository or sensitive task, use approval-based settings and grant only the access required. Protect secret files and avoid commands that can change external systems unless that access is necessary and explicitly reviewed. Anthropic documents configurable allow, ask, and deny rules. Its bypassPermissions mode is sensitive and is not a safe default.
A practical loop is: inspect the relevant code, make one bounded change, run the specified check if permitted, inspect the diff, and compare the result with the contract. Keep the unit of work small enough that a reviewer can understand the cause, change, and evidence without reconstructing an entire session.
When a check fails, provide the exact command and output. Ask for a root-cause analysis rather than a blind patch, request a focused fix, and rerun the same check. If the session repeats speculative edits, interrupt it, preserve the observed failure, narrow the task, and restart from that evidence.
Record a baseline test result where practical. If the suite already fails, the baseline helps distinguish a known failure from a regression, although it does not decide whether the change is correct. Protect uncommitted work before using Git commands that reset or discard changes. A clean rollback point should come from your team’s normal Git practices, not from assuming the agent can reconstruct lost work.
Do not widen permissions to rescue an unclear task. First decide whether the missing information is a requirement, a repository path, a test command, or an authorized credential. Resolve that specific gap, then grant the smallest additional access needed.
Verify the change before accepting it
Do not treat a plausible explanation or a passing command as proof that the change meets the requirement. Inspect changed files and the diff, run relevant tests and static checks, and compare observed behavior with every acceptance criterion. A passing suite is evidence for the checks it covers. It does not by itself establish business correctness, security, migration safety, or production readiness.
For frontend work, browser inspection can add evidence when Claude Code is connected to Chrome and the site is authorized. Anthropic’s Chrome integration documentation describes browser actions subject to browser, site, and session permissions. Use interactive inspection alongside deterministic tests and human design review, not instead of them.
Record exact commands and outcomes in the task or pull request. The following is an illustrative review record, not a Claude Code or ClickUp output schema:
{
"run_id": "ENG-482-payments-service-fix-retry-timeout-rev17-attempt1",
"task_id": "ENG-482",
"repository": "payments-service",
"source_revision": "requirements-rev17",
"files_changed": [
"src/retry.ts",
"src/retry.test.ts"
],
"commands_run": [
"[repository-documented test command]"
],
"test_results": [
"[observed result with exit status]"
],
"assumptions": [
"[unconfirmed assumption, or none]"
],
"unresolved_failures": [
"[failure, or none]"
],
"review_status": "pending-human-review"
}Keep records at the right grain. One run record represents one agent execution. One test record represents one test or suite result. One citation record represents one source requirement or decision. A daily or project rollup should be stored as an aggregate, not mistaken for another run.
If several workers or retries can operate concurrently, do not use a lookup followed by create as the only duplicate control. Use a database-enforced unique index and an atomic insert or upsert. An illustrative run key might be workspace_id + repository_id + task_id + source_revision + attempt_number. A pull-request record may instead use repository_id + head_commit_sha. These are implementation recommendations, not vendor-published Claude Code or ClickUp fields.
- The diff contains only understood, in-scope changes.
- Each acceptance criterion has a stated outcome or is marked unresolved.
- Relevant checks have recorded commands, exit statuses, and observed results.
- New failures are distinguished from recorded baseline failures where possible.
- Assumptions, security-sensitive changes, and remaining risks are disclosed.
- A human reviewer is identified under the team’s normal process.
Keep context useful and recover from a stuck session
Long sessions can encounter context-management or memory problems. Anthropic documents controls including /compact to compact context, /clear to start fresh, /resume to return to a session, and diagnostic commands such as /doctor and /context. Check the troubleshooting guide for current behavior and recovery steps.
Use /compact when the same task needs relevant history. Use /clear or a separate session when the task changes, so unrelated discussion does not steer the next request. Resume a session only if its state is still useful.
When a fix keeps failing, stop the loop and carry forward the goal, relevant files, exact failing output, remaining acceptance criteria, and verified environment details. Also check dependencies, branch state, and whether the failure predates the change. A shorter session grounded in evidence is usually more useful than a longer transcript of guesses.
Choose repository-first or workflow-first assistance
Claude Code is oriented around repository and command-line work. A project workspace can instead hold requirements, decisions, ownership, and delivery status. Choose where to start based on the actual blocker, not on a general claim that one tool is better.
| Situation | Useful starting point | Why |
|---|---|---|
| Clear code change with testable criteria | Repository | Inspect code, edit files, and run project checks. |
| Missing decision, owner, or acceptance criteria | Work system | Resolve the requirement before implementation. |
| Requirement in a task, implementation in a repository | Both | Keep the task as requirement and ownership context; keep code, pull-request, and CI evidence in the repository workflow. |
ClickUp documents connecting Codegen through its App Center and invoking it by assigning it to a task or mentioning @codegen. ClickUp markets Codegen for task-context coding and pull requests. The reviewed public pages do not specify its complete execution contract, branch behavior, retry semantics, output schema, or duplicate prevention. Confirm behavior in the connected workspace and review the resulting repository changes, checks, and scope before merge.
A defensible task-to-Codegen handoff therefore needs a task with a source requirement, repository and branch context, acceptance criteria, test expectations, and a named reviewer. Treat the resulting code or pull request as proposed work. If repeated or concurrent runs are possible, use a stable run identity and enforce uniqueness in the receiving system rather than assuming the invocation feature provides idempotency.
Keep the task or document as the source of requirement and ownership, and the repository, pull request, and CI as the evidence for code and tests. For teams designing bounded agent workflows, see ConsultEvo’s AI agent services and ClickUp setup and automation.
Frequently asked questions
Does Claude Code run tests automatically?
Claude Code can use command-line tools, but it does not know which checks define success unless you supply them or the repository instructions make them clear. Name the relevant test command and review its output.
Can Claude Code open a pull request?
Anthropic’s launch announcement describes GitHub commit and push capabilities. The exact result depends on configuration, permissions, branch policy, and repository workflow. Confirm the branch, diff, checks, and pull-request contents yourself.
Can Claude Code inspect a web app?
With the documented Chrome integration, it can perform browser actions subject to browser and site permissions. Treat those observations as additional evidence, not as a replacement for deterministic tests or human review.
Is AI-generated project documentation authoritative?
No. ClickUp’s AI documentation guidance says generated documentation needs human review and cannot verify technical accuracy or institutional context. Preserve links to the source requirement and technical evidence.