My Claude Code Setup for 2026: The Guardrails That Let It Work Autonomously

Jack Buchanan-Conroy — Sun, 17 May 2026 21:35:53 +0000

The autonomy isn't in the model. It's in the repo.

Most people who start using Claude Code go through the same arc. First session: it's brilliant, writes a feature in minutes, you feel like you've discovered some unfair advantage. Third session: it quietly refactors something it shouldn't have touched, formats files in a style that conflicts with your ESLint config, and confidently finishes a task that was 60% done. By week two, you're babysitting it on every step because you've been burned enough times to not trust it.

That's not an AI problem. It's an infrastructure problem.

I've been contracting as a principal engineer for over a decade (no CV, no job boards, just referrals) and I've watched this pattern repeat across teams. People expect autonomous AI coding to emerge naturally as models get smarter. It doesn't work that way. The model was already smart enough a year ago. What wasn't there was the engineering wrapper. The controls. The structure that makes it safe to let the agent work without you holding its hand.

This is what I've learned about building that structure.

Why "just give Claude the task" breaks down

Giving Claude Code a vague task in an uncontrolled repo is like hiring a brilliant contractor who's never seen your codebase, doesn't know your conventions, has no idea what's off-limits, and reports back only when they're done. You'd never do that with a human. But we do it with AI constantly.

The failure modes are predictable once you've seen them:

It reformats files you didn't ask it to touch. It makes architectural decisions mid-task because you didn't specify, and it picks whatever pattern it's seen most in training data, which may not be what you use. It decides a task is "complete" when it's technically done by some interpretation, but not by yours. It runs a command that works locally but breaks in CI. It writes a secret directly into a config file because nothing stopped it.

None of these are hallucinations. They're the agent making reasonable-seeming decisions in the absence of constraints. The fix isn't a better prompt. It's engineering controls that make bad decisions impossible or immediately visible.

CLAUDE.md: your repo's operating manual

The first thing to get right is CLAUDE.md. This file sits in your repo root and Claude reads it at the start of every session. Think of it as the onboarding document for a new engineer who learns fast but has no project context whatsoever.

Boris Cherny, the creator of Claude Code, puts it plainly: CLAUDE.md isn't a README for humans. It's persistent memory for the agent. Everything a senior engineer would tell a new joiner on day one: how to run the build, what the test command is, what patterns the team uses, what's off-limits. That goes here.

What actually goes in it:

# Project Operating Rules

## Commands
- Build: npm run build
- Test: npm run test:unit && npm run test:e2e
- Lint: npm run lint
- Never run npm install directly — use npm ci

## Hard rules
- Never modify .env files
- Never commit directly to main — always branch
- Don't touch files in /legacy without explicit instruction
- Do not add new dependencies without flagging them first

## Conventions
- All API types live in src/types/api.ts
- Error handling uses the centralised AppError class — no raw throws
- Styling via Tailwind only — no new CSS/SCSS files

## When in doubt
Stop, describe the ambiguity, and ask. The cost of pausing is near zero.
The cost of wrong edits is high.

Keep it short. Every line you add eats into the context window the agent needs for actual work. The SAP community guide I've found most useful makes the point bluntly: structure your rules with the most important ones at the top, because Claude pays more attention to content near the beginning.

One thing I now do after any code review: if a pattern surfaces that Claude got wrong, I add a rule. The file compounds. Over a few weeks, it becomes a genuinely useful operating constraint that stops you from seeing the same class of mistake twice.

Separate instruction files for different concerns

CLAUDE.md is the root, but it shouldn't carry everything. For larger projects, I split concerns into dedicated files in .claude/rules/:

.claude/
  rules/
    architecture.md    # System design decisions and why
    testing.md         # Coverage expectations, test patterns, what to mock
    security.md        # What never gets hardcoded, auth patterns, secrets handling
    style.md           # Code style beyond what linters enforce
    deployment.md      # What's safe to run vs what needs a human

The architecture file is the one most people skip and regret. It answers the questions that no linter can: why is this service split this way, why did we choose this state management approach, what's the seam between these two modules. Without it, the agent makes coherent but wrong architectural decisions constantly, and they're the hardest to unpick later.

The security file is the one that matters most for production codebases. Mine looks like this:

# Security Rules

## Absolute prohibitions
- Never hardcode API keys, tokens, or credentials — always use process.env
- Never log request bodies or headers that might contain auth tokens
- Never write to .env or .env.* files
- Never add curl | bash patterns in any script

## Auth
- All protected routes use the requireAuth middleware — no exceptions
- JWT validation happens in src/middleware/auth.ts — don't duplicate it

These aren't suggestions. They're constraints the agent needs to treat as non-negotiable.

Hooks: where "probably" becomes "always"

Everything before this section is documentation. Hooks are enforcement.

You can tell Claude in CLAUDE.md not to modify .env files. It will probably listen. If you set up a PreToolUse hook that blocks writes to .env files, it will always block them. For anyone working on production codebases, that distinction is everything.

Hooks are shell commands that fire at specific points in Claude's lifecycle. Before a tool runs. After a file is written. When the agent decides to stop. They're deterministic. They don't ask the model to make a good decision, they enforce the outcome you want regardless.

Here's my core settings.json setup:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "echo "$CLAUDE_TOOL_INPUT" | grep -qE 'rm -rf|curl.*\\|.*bash|DROP TABLE' && exit 2 || exit 0"
        }]
      },
      {
        "matcher": "Write|Edit",
        "hooks": [{
          "type": "command",
          "command": "./scripts/block-sensitive-writes.sh"
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [{
          "type": "command",
          "command": "npx prettier --write "$CLAUDE_TOOL_INPUT_FILE_PATH" 2>/dev/null || true"
        }]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [{
          "type": "command",
          "command": "./scripts/verify-completion.sh"
        }]
      }
    ]
  }
}

The Stop hook is underrated. By default, Claude decides it's done when it thinks it's done. A Stop hook that runs your test suite and returns exit 2 if tests are failing means Claude literally cannot declare completion until the work passes. It forces a self-verification loop.

The block-sensitive-writes.sh script checks the file path against a list of protected paths:

#!/bin/bash
FILE_PATH=$(echo "$CLAUDE_TOOL_INPUT" | jq -r '.file_path // empty')

BLOCKED_PATTERNS=(".env" ".env.*" "*.pem" "*.key" "*secrets*")

for pattern in "${BLOCKED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == $pattern ]]; then
    echo "Blocked: attempt to write to sensitive file $FILE_PATH" >&2
    exit 2
  fi
done

exit 0

One warning: if your Stop hook returns exit 2, Claude keeps working — which can cause an infinite loop. Always check the stop_hook_active field and allow stopping on subsequent invocations if it's set to true.

Pre-commit and CI as hard outer boundaries

Hooks operate inside Claude's runtime. Pre-commit hooks and CI operate outside it entirely. That's the distinction that matters.

Even with the best Claude setup, a human engineer can push without Claude. A dependency update can introduce a vulnerability. Someone runs a script that bypasses the agent completely. Pre-commit and CI are the backstop for everything, not just AI-generated changes.

My .pre-commit-config.yaml for any serious project:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: detect-private-key
      - id: check-merge-conflict
      - id: no-commit-to-branch
        args: ['--branch', 'main']

  - repo: https://github.com/Yelp/detect-secrets
    rev: v1.4.0
    hooks:
      - id: detect-secrets

  - repo: local
    hooks:
      - id: unit-tests
        name: Unit tests
        entry: npm run test:unit
        language: system
        pass_filenames: false
        always_run: true

The detect-secrets hook is the one I've seen catch things most people don't think about. Not just obvious keys, but high-entropy strings that pattern-match as credentials. Worth the setup time.

In CI, the principle is simple: whatever Claude did locally has to survive the same pipeline your human engineers use. No separate lenient pipeline for AI commits. Same lint rules, same test gates, same build checks. If it fails there, it fails. No exceptions for velocity.

Permission settings: what Claude can do freely vs what needs approval

Claude Code has a permissions system that's more granular than most people use. The default is to ask about most things, which is safe but slow. The goal is to give broad permission for safe operations and lock down anything with blast radius.

My settings.json permissions block:

{
  "permissions": {
    "allow": [
      "Bash(npm run lint:*)",
      "Bash(npm run test:*)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Read",
      "Glob",
      "Grep"
    ],
    "ask": [
      "Bash(git commit:*)",
      "Bash(git push:*)",
      "Bash(npm install:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(curl:*)",
      "Bash(wget:*)"
    ]
  }
}

The key insight from the SmartScope guide I've found most useful: permissions evaluate deny first. Setting sensitive files to deny makes them effectively invisible to Claude, which is more secure than blocking them via hooks (which still receive the attempt). For .env files and credential stores, deny is the right call.

Flagging git commit and git push as ask isn't about not trusting Claude. It's about maintaining a human checkpoint at the boundary where work becomes permanent and visible to the rest of the team.

Design tasks so the agent works in small reversible steps

The biggest workflow mistake I see isn't missing hooks or bad CLAUDE.md files. It's handing the agent a task that's too large to be safely reversible.

"Refactor the authentication module" is not an agent task. It's a project. When something goes wrong in the middle (and something will), you have a half-refactored codebase and no clean rollback point.

Break it down:

"Read the current auth module and write a summary of what it does to docs/auth-notes.md. Don't touch any code."
"Based on that summary, propose three approaches to the refactor. Write them to docs/auth-approaches.md. Still no code changes."
"Implement approach 2, one function at a time. After each function, run the unit tests and report the result before proceeding."

Each step produces something inspectable. Each step is reversible. The agent can't accidentally drift into a broken intermediate state because you've defined the checkpoints.

The pattern I use mentally: if a git revert on this task would feel scary, the task is too large. Aim for changes that can be cleanly undone in under thirty seconds.

What to log so you can audit what happened

If you're running Claude in any mode with meaningful autonomy, especially overnight or unattended, you need logs. Not because you don't trust it, but because when something looks wrong later, you need to know what happened.

A PostToolUse hook for basic audit logging:

#!/bin/bash
TOOL=$(echo "$CLAUDE_TOOL_INPUT" | jq -r '.tool_name // "unknown"')
FILE=$(echo "$CLAUDE_TOOL_INPUT" | jq -r '.file_path // empty')
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

echo "{"ts":"$TIMESTAMP","tool":"$TOOL","file":"$FILE"}" >> ~/.claude/audit.jsonl

After 108 hours of autonomous operation logged and analysed (there's an excellent open-source collection of this on DEV Community by yurukusa), the most useful signals turned out to be: which files were touched, in what order, what commands ran, and how long the session ran. Not the content of changes. Git history covers that. The operational trail of decisions.

I also keep a LESSONS.md in every repo I use Claude heavily on. When Claude makes a class of mistake, I document it:

## 2026-05-12: Context about rate limiter

Claude kept adding a new rate limiter in middleware rather than using
the existing one in src/lib/rateLimit.ts. Added explicit note to
architecture.md and a reference in CLAUDE.md.

The structured incident log means Claude doesn't repeat the same category of mistake across sessions. It compounds the knowledge the same way a good post-mortem process does for a team.

The autonomy ladder

The mistake is trying to jump straight to full autonomy. There's a progression that actually works, and rushing it just means more cleanup.

Level 1: Suggestions only. No writes. Claude reads, proposes, you implement. Annoying after a while, but useful for the first week in a new repo. You find out quickly whether it understands your patterns or not.

Level 2: Edits with approval gates. Claude writes code, but you confirm every file change before it lands. Slow. The point isn't the speed. You're building a mental model of what the agent gets right and where it consistently drifts. Most people skip this level. They shouldn't. You end up knowing exactly which rules your CLAUDE.md is still missing.

Level 3: Test-driven tasks. Write a failing test. Hand it to Claude. Tell it to make the test pass without breaking anything else. That's the entire spec. The CI gate does the verification. This is where productivity genuinely picks up, because the feedback loop is mechanical rather than conversational. Claude can't wriggle out of a red test the way it can wriggle out of an ambiguous instruction.

Level 4: Bounded background tasks. Larger scope, defined completion criteria, hook-enforced quality gates before it can commit anything. You review the final diff before it merges. Push off a task at 11pm, check the branch in the morning. But you only get clean overnight runs after you've been through Level 3 enough times to know where your constraints have holes.

Most teams are ready for Level 3 within a week if they've done the CLAUDE.md and hooks work properly. Level 4 takes a month of working through the failure modes.

The actual thesis

AI coding agents don't become autonomous because the model gets smarter. They become autonomous when the repo becomes harder to damage.

Every control described here (CLAUDE.md, the separated instruction files, the hooks, the permission settings, the pre-commit gates, the CI pipeline, the task decomposition discipline, the audit logs) is just good engineering practice. It works on every engineer in the codebase, human or AI. The reason you're adding it might be Claude, but the controls themselves aren't AI-specific.

Teams aren't failing because the model can't code. They're failing because there's nothing stopping it from coding badly.

When it works, really works, you push off a task at 11pm, sleep, and the branch is sitting there in the morning with passing tests and a JSONL file of everything that ran. That's the target. Not a smarter model. A tighter container.

Build that, then step away.

If this was useful, I write about engineering, contracting, and building products at @jackbcai. The code snippets above are production-tested — not examples invented for the article.

DEV Community: Jack Buchanan-Conroy