My Claude Code PR workflow

AI coding agents are useful when they make engineering work more inspectable. They are risky when they make work feel finished before it has been understood.

My Claude Code workflow is built around that distinction. I use the agent to compress mechanical effort: repo inspection, implementation drafting, verification, PR summaries, and repeated checks. I do not use it to skip judgment. The useful pattern is not "ask AI to code." It is "make every step of the change easier to inspect."

Start with repo orientation

The first step is always inspection. Before changing code, I want the agent to answer basic questions:

• What branch are we on?
• Is the worktree clean?
• Which files probably own this behavior?
• What patterns already exist nearby?
• What command proves the change works?

This step is not ceremony. It prevents the most common AI failure mode: generating plausible code that ignores the actual system.

I prefer tool-driven inspection over guesses. Search the codebase. Read the relevant files. Check package scripts. Look at existing tests. If the agent proposes a solution before doing that, I slow it down.

Write a small plan

For meaningful changes, I want a short plan before edits. Not a long strategy document. A practical plan:

1. Update the data model.
2. Render the new state in the component.
3. Add responsive CSS.
4. Run build and browser checks.
5. Commit and update the PR.

The plan should name the expected files and the verification path. This creates a shared contract. If the implementation starts drifting into unrelated refactors, the plan makes that visible.

Keep changes reviewable

AI can create large diffs quickly. That is not always good. A large diff may be correct, but it is harder to review and easier to hide accidental behavior changes.

I push the agent toward focused changes:

• Use existing helpers before adding new abstractions.
• Match local naming and file boundaries.
• Avoid unrelated cleanup.
• Keep style changes scoped to the feature.
• Do not rewrite components just to make the diff feel cleaner.

The best AI-assisted PRs are often boring. They read like a careful engineer had more typing speed.

Verify like a skeptic

Verification is where the workflow earns trust. I do not treat a successful build as enough for user-facing changes.

For frontend work, I usually want:

• npm run build
• a browser check of the changed route
• mobile and desktop layout checks
• no horizontal overflow
• confirmation that links, downloads, or forms do what they claim
• a quick scan for console errors

For backend or data work, I want the closest possible runtime check: query the table, call the endpoint, run the migration locally, or execute the test suite that covers the affected behavior.

Use AI review as a checklist, not a verdict

I sometimes ask the agent to review its own work or to look for bug risks. That can be useful, but only if treated as a checklist. The agent may find real issues. It may also invent concerns that do not apply.

The engineer still has to verify. If the review says "possible accessibility issue," inspect the markup. If it says "potential race condition," trace the state. If it says "missing test," decide whether the risk actually warrants one.

AI review is a prompt for attention, not an authority.

Write the PR for the next human

A good PR description should explain:

• what changed
• why it changed
• how it was verified
• what risk remains

If a reviewer cannot understand the intent from the description and the diff, the agent did not make the team faster. It moved ambiguity downstream.

I also like PRs that mention what did not change. "No schema changes." "No runtime Supabase writes." "No change to existing public routes." Those notes reduce review uncertainty.

The operating principle

The workflow is simple: inspect first, plan narrowly, implement in the local style, verify like a skeptic, and write the PR for the next human.

Where this workflow breaks

This workflow breaks when the agent is allowed to optimize for momentum over evidence. The warning signs are easy to spot: it stops citing files, it stops running checks, it changes unrelated modules, or it explains the diff in general terms instead of concrete behavior.

It also breaks when the human stops reading. AI can make a polished PR description for a weak change. It can summarize tests that do not cover the risky path. It can sound confident about a framework pattern that does not match the codebase. The process only works if the engineer remains skeptical.

Team version

On a team, I would make the workflow explicit. Define which checks are mandatory for frontend work, which commands prove backend changes, and what belongs in the PR description. Ask agents to produce the same reviewable artifacts every time: plan, diff summary, verification, known risks.

That consistency matters more than the specific agent. The team should be able to evaluate the work without decoding the prompting style behind it.

AI makes that loop faster. It does not make the loop optional.