Claude Code Operator’s Guide

Claude Code Operator’s Guide

Claude Code is Anthropic’s agentic command-line tool. It lets you delegate complex coding tasks from the terminal while keeping control over what changes and when. The tool is only as good as how you drive it — the gap between frustrating and transformative results comes down to how you set up project context, permissions, and workflow. This guide is the setup.

The pattern throughout is the same: you set context and gates; the agent plans and executes against them.

1. Project memory: CLAUDE.md

Give Claude stable memory through a well-structured CLAUDE.md — the project’s operating constitution, defining standards, constraints, and navigation that persist across sessions.

Initialize it:

npm install -g @anthropic-ai/claude-code
cd your-project
claude
> /init

Structure it so the agent can find what it needs fast:

# Project Overview
- One-liner: "TypeScript API for real-time collaboration"
- Architecture: Event-driven with Redis pub/sub
- Domain: Users, Documents, Permissions

# How to Run
- Build: npm run build
- Test: npm run test
- Typecheck: npm run typecheck

# Coding Standards
- TypeScript strict mode, no `any` types
- API errors use Result<T, E> pattern
- All functions must have unit tests

# Docs Map
- /docs/architecture/system-design.md
- /docs/specs/api-v1-spec.md
- /docs/plans/current-sprint-plan.md

# Anti-patterns (DO NOT)
- No nested ternaries beyond 2 levels
- No copy-paste of type definitions
- No direct database queries in controllers

Tip: modularize large projects with memory imports — reference external files with @docs/... syntax to keep the main memory file focused.

2. Permissions and safety rails

The permission system is a strength, but defaults can create approval fatigue. Tune .claude/settings.json to cut friction without giving up safety:

{
  "permissions": {
    "allow": [
      "Bash(npm run test:*)",
      "Bash(git diff:*)",
      "Read(~/.zshrc)"
    ],
    "deny": ["Bash(curl:*)"]
  },
  "defaultMode": "acceptEdits",
  "model": "claude-sonnet-4-20250514"
}

For prototyping, use auto-accept with clean git checkpoints so rollbacks are cheap. For production code, keep synchronous supervision and step through changes.

3. Plan first, then build

The highest-leverage habit: start every significant feature with a written plan you and the agent both follow. It prevents scope creep and creates natural checkpoints.

# Feature: User Authentication — Plan

## Goal
Implement JWT-based auth with refresh tokens

## Non-Functional Requirements
- 15min access tokens, 7-day refresh
- Redis for token storage
- Rate limiting: 5 requests/minute per IP

## Impacted Areas
- /src/auth/ (new module)
- /src/middleware/auth.ts
- /tests/auth/

## Steps
- [ ] S1: Create types and interfaces
- [ ] S2: Implement JWT service
- [ ] S3: Add auth middleware
- [ ] S4: Write integration tests

## Risks & Rollback
- Risk: Token storage race conditions
- Rollback: Revert to stateless JWT if Redis fails

## Done Definition
- All tests passing
- Security review complete
- Documentation updated

Then execute the plan one step at a time, gating on tests:

> read @docs/plans/auth-feature.md
> critique this plan; propose safer, smaller steps
> execute S1 only; show diff; run tests
> if tests pass, proceed to S2

4. Specialized sub-agents

Sub-agents are focused assistants with narrow roles and separate context windows — the fix for the “jack of all trades” problem. Define four core agents in .claude/agents/:

Planner (planner.md)

---
name: planner
description: Architecture-first planner. Produces minimal, verifiable steps.
tools: Read
---
You create: scope definition, constraints, file impact analysis,
stepwise implementation plan, risk assessment, and test strategy.
Never proceed to implementation — planning only.

Implementer (implementer.md)

---
name: implementer
description: Executes approved plans with small commits and continuous testing.
tools: Read, Edit, Write, Bash
---
Follow plan checkboxes strictly. After each step: run tests,
summarize changes, note any blockers. No architectural decisions.

Reviewer (reviewer.md)

---
name: reviewer
description: Security and quality review after implementation steps.
tools: Read, Grep, Bash
---
Security checklist: injection attacks, secrets exposure,
authentication/authorization, error handling, performance, test coverage.
Provide concrete fix suggestions only.

Researcher (researcher.md)

---
name: researcher
description: Low-context research for library comparisons and trade-offs.
tools: Read
---
Research libraries, patterns, and best practices. Return concise
findings with recommendations and trade-off analysis. Cite sources.

Invoke them by role:

> use the planner agent to design the auth system
> use the implementer agent to execute step 1 of the plan
> use the reviewer agent to check for security issues

5. Test-driven loops

Claude Code is strong at test-first work because it can write tests, run them, read failures, fix code, and iterate to green in one session:

> find functions in AuthService.ts not covered by tests
> add comprehensive tests for AuthService including edge cases
> run the new tests and fix any failures
> add integration tests for the auth endpoints
> run all tests and ensure 100% pass rate

Encode your standards as a reusable slash command so the gate is one keystroke:

.claude/commands/quality-gate.md

---
description: Run tests, check coverage, fix failures until green
allowed-tools: Bash(npm run test:*)
---
Run all tests and fix failures. Ensure >90% coverage.
Keep diffs minimal and explain root causes of failures.

> /quality-gate

6. Patterns that scale

Slash commands for team workflows — turn repeated prompts into commands that capture institutional knowledge:

.claude/commands/deploy-checklist.md

Review code for:
- Environment variable usage
- Database migration safety
- Breaking API changes
- Performance impact
Then generate deployment notes.

MCP integration — expose external systems safely to agents with complex toolchains:

{
  "enabledMcpjsonServers": ["github", "filesystem", "postgres"],
  "mcpSettings": {
    "github": {
      "permissions": ["read_repos", "create_prs"]
    }
  }
}

Git worktrees for parallel work — isolate long-running sessions:

git worktree add ../feature-auth feature/auth
cd ../feature-auth
claude --resume auth-session-id

7. The daily loop

  1. Explore & plan — analyze architecture, identify files, propose a plan, write it to @docs/plans/.
  2. Execute small steps — read the plan, run Step 1, show the diff, run tests. Do not proceed until approved.
  3. Review & integrate — use the Reviewer agent, run the full suite, open a PR.
  4. Resume & iterate — claude --continue to pick up context.

The discipline that makes it work: keep changes small with clean git history, let the agent run tests and fix issues but review architectural decisions yourself, gate quality with sub-agents after each major change, and always keep a clean state you can revert to.

Getting started

  1. Install: npm install -g @anthropic-ai/claude-code
  2. Set up memory: create CLAUDE.md with your standards.
  3. Configure: balance safety and speed in .claude/settings.json.
  4. Plan: write one feature plan and execute it step by step.
  5. Specialize: add a reviewer agent for quality control.

For the productized, multi-mode version of these patterns, see Oh My Claude Code.

This entry was posted in . Bookmark the permalink.
Adam Bernard