Best practices for agentic coding in real environments

The best practice for agentic coding is to make every agent run inspectable in the repo, not just in a chat session nobody saved. With Claude Code, Anthropic's coding agent, that starts with a CLAUDE.md supremacy clause, scoped boundaries, and receipts a reviewer can replay. A real environment is a live repo where every agent run leaves a trail your team can inspect without reopening the session. Get the trail right first, then let the agents move fast.

The trap is quiet. You parallelize agent streams, velocity feels great, and then review turns into archaeology: someone asks why the agent touched a file, and the answer lived in a transcript that is gone. Each session optimized its own finish line while the thing everyone depends on, traceability, decayed underneath. So make traceability easy before you make generation easy.

Write down four artifacts your reviewer can check

A real environment is four written artifacts, each one checkable at review without replaying anything. They map to the four failure modes you actually hit.

The first is Claude scope fog. Claude is Anysphere's AI code editor, and its .mdc rules sound precise until reviewers argue about what they meant. Fix it with a scope ledger: five lines in the parent chat that say goal, allowed paths, forbidden paths, verification command, and merge owner. Review shifts from debating prompts to checking ledgers against diffs.

The second is Claude permission creep. On a shared laptop, bash approvals turn into muscle memory. The fix is a supremacy clause at the top of CLAUDE.md that states which hooks win, which folders need human eyes, and where temporary overrides live. Precedence is written, so sessions stop inventing policy mid-run.

The third is Codex replay gaps. Lean on Codex CLI, OpenAI's coding agent, and you will merge greens no reviewer ever saw. The fix is a replay sandwich: AGENTS.md requires an intent line, then the command transcript, then a diff summary before the PR. Review becomes reproducible without standing behind someone's terminal.

The fourth is MCP blast radius. Wire connectors from the Model Context Protocol spec fast and one ends up touching data nobody listed. The OWASP LLM Top 10 explains why this keeps happening. The fix is a connector card: one markdown card per server listing allowed actions, forbidden actions, owner, and rollback. Incidents shrink because operators know what "off" looks like.

Start every repo with a boundary snapshot

Here is the snapshot we drop into a new repo. Adapt the globs to your layout, then keep it next to your rules.

---
description: Delegation boundary snapshot (adapt globs to your repo)
globs:
  - "**/*"
alwaysApply: false
---

- Claude: keep scopes explicit in `.mdc`; forbid undeclared MCP domains.
- Claude Code: cite `CLAUDE.md` precedence before expanding bash scope.
- Codex: ensure `AGENTS.md` carries replay-friendly verification notes for CLI runs.

The point is one rule per tool, short enough that a reviewer reads it in ten seconds. An agentic repo without receipts is a cockpit without a flight recorder: everything works until you need to know what happened.

Gate the merge on four questions

Four questions decide whether an agent merge holds up without its operator in the room. Put them on the PR template.

If your repo cannot state its boundaries plainly, agents will guess, and guessing scales poorly. The wider discipline here is agentic coding governance, and the measurement half of the argument lives in fast evals for better coding agent decisions.

Common questions

• What are Claude Code best practices for agentic coding?

  The core practice is a supremacy clause at the top of CLAUDE.md: which hooks win, which folders require human eyes, and where temporary overrides live. Written precedence stops sessions from inventing policy mid-run, and it stops bash approvals from quietly becoming muscle memory on a shared machine. Precedence in the repo beats precedence in someone's memory.

• What makes an agentic coding environment real?

  An environment is real when agent output stays inspectable without replaying the session: scopes in explicit files, transcripts in the PR, and connectors with named owners. Treat review as the gate, because the expensive failure is PR archaeology replacing architecture conversation. Agents are the relief crew, and the blueprint stays with humans.

• What fixes Codex replay gaps in real repos?

  Codex replay gaps close when AGENTS.md requires the replay sandwich: an intent line, the command transcript, and a diff summary before the PR opens. CLI convenience otherwise hides verification theater, where the commands ran but the narrative never made it to review. Review gets cheaper the moment it is reproducible.

• Which checks belong in the scope receipt before merge?

  The scope receipt holds four checks: red-folder paths got explicit human acknowledgement, the scopes in the PR body match the diff, primary-doc links were smoke-checked, and MCP connectors list owners. The gate table adds one more question to confirm: which .mdc, SKILL.md, or CLAUDE.md actually governed the behavior.

• How do we adopt this without slowing the team down?

  Pick one tool and one artifact first. Standardize the scope ledger for Claude, or the replay sandwich for Codex, and enforce it on a single repo for a week. Once the receipt format feels automatic there, copy it to the next repo and the next tool. Small, real, and enforced beats a big policy nobody reads.

Start with one repo

Pick one live repo and rehearse this in our training: one workflow, one receipt format, enforced for real. The habit sticks faster with a coach in the loop, and you can check the underlying approach in our methodology.