Let Coding Agents Work Safely

Coding agents write code autonomously by reading repo context, planning a change, editing files, running tools, and asking for review when the workflow says they should stop. The safe version is not “let the agent roam”; it is “give the agent a small state machine, clear tool boundaries, and review gates.”

AI coding governance is the set of team rules that decides what an agent may read, change, run, and merge. For Claude Code, Anthropic's coding agent, that usually means a good CLAUDE.md, scoped skills, MCP boundaries, hooks, and a review convention the whole team understands.

This is the useful middle ground for agentic coding: enough autonomy to improve developer productivity, enough friction to keep production boring. It also makes AI coding training easier, because the workflow is written down instead of living in one senior engineer's head.

Give the agent a workflow, not a vibe

Start by naming the states your agent is allowed to move through. A simple team workflow is intake → plan → edit → test → review → merge-ready. That is enough structure for most coding agents without turning every task into ceremony.

This matters because autonomous tools tend to blur steps. An agent can read an issue, change files, run tests, and draft a pull request in one long burst. That feels fast, but it makes it harder to see whether the plan was reasonable before the code appeared.

The trap is encoding the workflow only in a prompt. Put the durable rule in repo memory, then use task prompts for the local goal. In Claude Code, a root CLAUDE.md can hold the team contract while nested CLAUDE.md files handle package-level rules.

A useful fragment looks like this:

# Agent workflow

Before editing, summarize the task in 3 bullets and list the files you expect to touch.

Do not move from planning to editing until the plan names:
- the user-visible behavior being changed
- the tests or checks that will prove it
- any migration, permission, or API-risk concern

After editing, report:
- files changed
- commands run
- tests that passed or could not be run
- review risks

This is the same idea behind workflow-harness projects that model agent work as a state machine. The important part is not the specific harness. The important part is that your team can tell which state the agent is in and what evidence is required before it moves on.

Put durable rules where Claude Code will see them

Use CLAUDE.md for rules the team wants Claude Code to apply repeatedly. Keep it short. The best memory files read like repo documentation, not a legal contract.

For a real repo, split rules by scope. The root file can say “never modify generated files” and “use pnpm test --filter for package checks.” A nested file in apps/billing/CLAUDE.md can say “all billing changes need an idempotency note and a rollback note.”

This matters for ai coding agents because context is part of the control plane. If the agent does not know your architecture constraints, it will infer them from nearby code. Sometimes that works. Sometimes it confidently copies the wrong pattern.

The trap is dumping everything into one root file. Long global memory gets ignored by humans and diluted for agents. Prefer sharp rules, local scope, and links to deeper docs only when the agent actually needs them.

For team skills, use the same discipline. A Claude skill should package one reusable capability, such as “write a safe migration plan” or “review an API change,” with scripts, templates, and reference notes close by. Good skills are small enough to activate at the right moment.

Draw MCP and hook boundaries before rollout

Model Context Protocol, or MCP, is an open protocol for connecting AI systems to external tools and data sources. In an engineering workflow, that can mean GitHub, issue trackers, docs, databases, design files, internal search, or deployment systems.

Treat MCP access like production access. Reading a GitHub issue is not the same risk as writing to a database, creating a release, or posting in a customer-facing Slack channel. Your convention should say which tools are read-only, which require confirmation, and which are off-limits.

Hooks are the other boundary. Use them for cheap, deterministic checks: formatting, secret scanning, generated-file detection, package-specific tests, and “you are editing outside the approved path” warnings. Do not ask a language model to remember something a hook can enforce.

The trap is giving broad tool access because the demo looks better. For ai coding governance, broad access should be earned by repeatable evidence: passing checks, small changes, and review history. This is where an agentic coding governance training path helps teams align before they standardize on one AI IDE.

Paste this team convention into a repo

Use this as a starter convention. Put it in the root CLAUDE.md, or in AGENTS.md if your team wants cross-tool instructions that can be reused by Claude Code, OpenAI Codex, OpenAI's coding agent, and Claude, Anysphere's AI code editor.

# Coding agent operating convention

## Purpose

Use coding agents for scoped engineering work where the task, files, checks, and review owner are clear.

## Allowed workflow states

- Intake: read the issue, linked docs, and relevant repo memory.
- Plan: propose the smallest safe change and list expected files.
- Edit: change only files named in the plan unless the agent explains why.
- Test: run the narrowest meaningful checks first, then broader checks if needed.
- Review: summarize behavior changes, risks, commands run, and files touched.
- Merge-ready: human reviewer confirms the diff, tests, and rollout notes.

## Stop rules

The agent must stop and ask before:
- changing authentication, billing, permissions, encryption, or data retention logic
- modifying production infrastructure or deployment configuration
- adding a new dependency
- deleting data, migrations, or generated artifacts
- using an MCP tool with write access
- editing outside the planned file set

## MCP permissions

- GitHub issues and pull requests: read allowed; write requires confirmation.
- Internal docs: read allowed for linked task context only.
- Databases: schema read only; no data writes.
- Slack or chat tools: no posting without explicit human approval.
- Deployment tools: no access from coding-agent sessions.

## Hook checks

Before review, run the checks that match the touched area:
- formatter or linter
- typecheck
- package-level tests
- secret scan
- generated-file check

If a check cannot run, explain why and name the human follow-up.

## Review checklist

The pull request is not merge-ready until the reviewer can answer yes:
- Is the task scope still small?
- Did the agent follow the planned workflow states?
- Are MCP/tool uses listed?
- Are tests or skipped checks documented?
- Are risky areas called out plainly?
- Is rollback obvious for production-facing changes?

The adoption path should be boring. One engineer proposes the convention in a pull request, two maintainers review it, and the team tries it for one sprint on real work. After that, move durable rules into CLAUDE.md, shared rules into AGENTS.md, and reusable procedures into skills or slash commands.

The review rule is the enforcement mechanism: no agent-authored pull request is merge-ready unless the reviewer can point to the plan, checks, MCP/tool use, and stop-rule decisions. For a deeper companion pattern, see How Autonomous Coding Agents Ship Safely.

Train the team on the review habit

Engineering team training should focus less on prompt cleverness and more on shared inspection habits. Everyone should know what a good agent plan looks like, what tool use should be disclosed, and when to stop the run.

The practical version of “how ai coding agents write code autonomously” is a loop: gather context, plan, edit, run checks, summarize evidence, and wait at the gate. Your workshop should make that loop visible with one real issue from your repo, not a toy app.

The trap is treating code review guardrails as anti-productivity. They are what let teams increase autonomy safely. Once the checklist is routine, reviewers spend less time reconstructing what happened and more time judging whether the change is right.

There are limits. A convention will not make an agent understand your business domain, and it will not replace ownership for security-sensitive changes. It gives the team a common operating model, which is the piece many coding agents news demos skip.

Common questions

• How do AI coding agents actually write code on their own?

  AI coding agents work by turning context into a plan, applying edits through tools, running checks, and iterating on failures. The citable caveat is that autonomy is bounded by permissions: files, shell commands, MCP servers, hooks, and human review decide how far the agent can go.

• Should we use CLAUDE.md or AGENTS.md for team rules?

  Use CLAUDE.md for Claude Code-specific memory and AGENTS.md for rules you want multiple tools to share. A good split is root-level repo rules in one shared file, then nested Claude files for package-specific behavior that only Claude Code needs during a session.

• Where should MCP access stop for coding agents?

  MCP access should stop before irreversible writes, production systems, broad customer data, and external communication. A practical baseline is read-only access for issues and docs, schema-only access for databases, and explicit human approval for any tool that writes, deploys, posts, or changes permissions.

• Do workflow states slow engineers down?

  Workflow states add a small pause before editing, but they usually save review time on non-trivial changes. The useful number is not seconds saved in generation; it is whether the pull request includes four things: plan, files changed, checks run, and risks called out.

• Can this work across Claude Code, Codex, and Claude?

  Yes, if the convention describes behavior instead of product UI. Keep the shared rules in plain Markdown, then map them to each surface: Claude Code memory and skills, Codex CLI instructions, Claude agent settings, hooks, and the MCP servers your team permits.

Further reading

• Model Context Protocol — specification
• Claude — Agent
• Claude Code — getting started
• OpenAI Developers — Codex quickstart
• GitHub — openai/codex
• GitHub — anthropics/skills
• OWASP — Top 10 for Large Language Model Applications
• NIST — AI Risk Management Framework
• Google Search Central — helpful, people-first content
• Google Search Central — generative AI content guidance

Start with one safe lane

Pick one repo, one class of task, and one reviewer group. Add the convention, run it for a sprint, then tighten the stop rules where review felt uncertain.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.