Skip to content

Claude Code: Terminal-Native Agentic Coding and Repository Refactoring

  • How Claude Code operates as a terminal-native agentic coding partner built by Anthropic.
  • Architecture: tool calling loops, file inspection, shell command execution, and git integration.
  • How to configure project conventions, tech stack rules, and test mandates using CLAUDE.md.
  • Extending Claude Code with custom tools, slash commands, MCP servers, and skills.
  • Security controls: command approvals, read/write boundaries, and safe autonomous loops.

Claude Code is Anthropic’s agentic command-line software development companion. Rather than operating as an editor extension or visual chat sidecar, Claude Code runs directly inside the developer’s terminal. Driven by Anthropic’s frontier foundation models—including Claude Opus 5.5 and Claude Sonnet 5.5—it pairs reasoning with local shell access, file read/write tools, and git version control. It autonomously reads repository file structures, plans edits across multiple files, executes compilers and test runners, inspects error traces, and creates git commits while keeping the developer in command through granular approval controls.

Software developers spend significant cognitive energy context-switching between code editors, web browsers, and command-line terminal sessions:

  1. Repetitive multi-file refactoring: Making a structural change (such as adding an auditing column across domain models, repository interfaces, and migration files) requires manually jumping across dozens of files.
  2. Disconnected test-fix loops: Developers run tests in a terminal, copy error stack traces into a browser chat window, paste generated code back into an editor, and switch back to the terminal to re-run the build.
  3. Editor lock-in: Most advanced AI coding tools require adopting specific proprietary IDE forks (such as Cursor or Windsurf). Engineers who prefer Neovim, Emacs, tmux, or custom terminal environments are forced into unfamiliar editors.

Claude Code solves these pain points by operating directly inside the terminal. It works alongside any editor, automating the edit-build-test-commit cycle in the developer’s native shell.

Claude Code executes a continuous tool-use feedback loop directly against your local operating system:

[Developer Prompt / Feature Request]
│
▼
[Claude Reasoning Engine]
(Selects next action: read, write, or bash)
│
┌──────────┴──────────┐
▼ ▼
[File System Tools] [Bash Tool Execution]
(Read files, search (Compilers, pytest,
grep, apply diffs) linters, git commands)
│ │
└──────────┬──────────┘
▼
[Developer Approval]
(Auto-approved for reads, prompt for risky writes)
│
▼
[Tool Result Feedback]
(Terminal stdout/stderr & test exit codes)
│
▼
[Iterate Until Tests Pass]
│
▼
[Git Commit Creation]

Claude Code includes built-in file manipulation tools:

  • File Reader & Glob: Inspects specific files or searches file trees without loading entire gigabyte directory trees into memory.
  • Grep & AST Search: Fast regex search across repository files to locate symbol definitions, imports, and usages.
  • Unified Diff Patching: Generates concise, surgical diffs rather than rewriting entire 1,000-line source files, preserving existing whitespace, comments, and unrelated functions.

Unlike browser assistants that output instructions for you to copy, Claude Code executes commands directly:

  • Runs build systems (npm run build, cargo check, go test, dotnet build).
  • Formats code with local tools (prettier, black, gofmt).
  • Inspects git status, stages changed files, and writes detailed, conventional commit messages.

Claude Code installs natively across operating systems:

Terminal window
# macOS / Linux / WSL native installation
curl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShell installation
irm https://claude.ai/install.ps1 | iex
# Launch in your repository root
cd my-project
claude

Note: Legacy npm global package installations (@anthropic-ai/claude-code) have been superseded by native platform binaries that auto-update cleanly without Node.js dependencies.

Every repository can define a persistent guide file named CLAUDE.md at its root. Claude Code ingests this file on every turn, ensuring it adheres to team standards without repetitive prompting:

# OrdersPortal Project Guide
## Technology Stack
- Backend: Go 1.24 with Gin and PostgreSQL
- Database: pgx/v5 with Goose migrations
- Testing: Go standard testing with testify/assert
## Build & Test Commands
- Build: `go build ./cmd/orders`
- Test all: `go test -v ./...`
- Lint: `golangci-lint run`
## Development Conventions
- Handlers never access database queries directly; use domain repository interfaces.
- Every new database migration requires both an Up and a Down SQL script.
- All monetary amounts must use the `currency.Amount` value object; never use raw floats.
- Never commit `.env` or credentials.

Advanced capabilities: skills, MCP, and memory

Section titled “Advanced capabilities: skills, MCP, and memory”

Claude Code natively integrates with external data stores and enterprise systems through the Model Context Protocol (MCP):

  • Connect to GitHub MCP servers to review open issues and pull requests.
  • Query local PostgreSQL or SQLite databases to inspect real schemas and test data.
  • Integrate with Jira, Confluence, and Atlassian toolchains; see MCP Architecture.

Skills allow developers to extend Claude Code with custom domain workflows (e.g., scaffolding an API endpoint according to organizational architecture templates); see the Claude Code Skills guide.

In long refactoring sessions, token usage grows. Claude Code provides built-in commands:

  • /compact: Summarizes conversation history while retaining crucial architectural decisions, freeing up context window space.
  • /clear: Resets active session memory while preserving CLAUDE.md project rules.
  • /cost: Displays real-time API token consumption and session expenses.

Realistic worked example: refactoring an idempotent payment refund handler

Section titled “Realistic worked example: refactoring an idempotent payment refund handler”

Consider an issue in OrdersPortal where a refund endpoint in Go lacks idempotency, causing duplicate credit card transactions when network retries occur.

The developer launches Claude Code in the project root:

$ claude "In internal/handlers/refund.go, the ProcessRefund handler lacks idempotency checking.
Add an Idempotency-Key header check, update the database repository to record the key in a transaction,
and write unit tests verifying that re-sending the same key returns the cached 200 response without re-charging."
  1. Research: Claude Code reads internal/handlers/refund.go and internal/repository/payment.go.
  2. Implementation:
    • Edits refund.go to extract Idempotency-Key from request headers, validating RFC 4122 UUID syntax.
    • Updates the repository transaction to query the idempotency_records table with row locking.
    • Adds unit tests in internal/handlers/refund_test.go covering both fresh requests and duplicate replay attacks.
  3. Verification:
    • Executes go test -v ./internal/handlers -run TestProcessRefund_Idempotency.
    • Tests pass cleanly on the first run.
  4. Git Commit:
    • Stages modified files and creates a commit: feat(payments): enforce idempotency key on refund processing.

Claude Code vs. Cursor vs. Antigravity vs. Codex

Section titled “Claude Code vs. Cursor vs. Antigravity vs. Codex”
Dimension Anthropic Claude Code Cursor Google Antigravity OpenAI Codex
Form factor Terminal CLI VS Code Fork IDE Agentic IDE + Terminal Cloud Micro-VM OR CLI
Editor requirement None (works with Neovim, Vim, tmux, VS Code) Requires Cursor IDE Requires Antigravity IDE None
Model access Claude Opus 5.5 & Sonnet 5.5 Multi-model (Claude, GPT, Gemini) Gemini 4 (Argon / Carbon) GPT-6.1 (Terra / Sol)
Context window 1 Million tokens 200K–1M tokens 1 Million+ tokens ~1 Million tokens
Execution safety Granular bash command approvals IDE agent permissions Dual-tier terminal sandbox Isolated cloud VM container
Project configuration CLAUDE.md .cursorrules / .cursor/rules Custom project settings Repository instructions
  • Editor independence: Works with any text editor; ideal for developers invested in custom keyboard layouts and CLI tooling.
  • Deep reasoning over complex diffs: Claude Opus 5.5 excels at catching subtle edge cases in concurrent, distributed, or systems-level code.
  • Iterative autonomy: Capable of reading compiler errors, revising code, and running tests multiple times until green.
  • No visual GUI previews: Does not render web UI mockups or HTML widgets side-by-side like browser Artifacts or IDE webview panes.
  • Terminal output verbosity: Running high-volume log builds through the terminal requires careful filtering to avoid context window flooding.
Scenario Recommendation Alternative
Large-scale codebase refactoring, migrations, and bug fixes across multiple files Use Claude Code —
Developers working in Neovim, Emacs, or remote SSH terminal sessions Use Claude Code —
Visual UI development requiring real-time rendered CSS/HTML previews Compare with Claude.ai or Cursor Claude AI or Cursor
Asynchronous cloud PR creation where local machine is completely offline Compare with Codex Cloud OpenAI Codex
Workloads tightly bound to Google Cloud tooling (BigQuery, Cloud Run) Compare with Antigravity Google Antigravity

1. How does Claude Code’s CLAUDE.md architecture differ from ephemeral prompt engineering? Ephemeral prompt engineering requires developers to manually repeat stack constraints, lint commands, and architectural rules in every new session or prompt turn. CLAUDE.md acts as persistent, deterministic project memory. Claude Code automatically ingests this file upon launching in the directory, conditioning the model’s system context with authoritative build commands, test patterns, and architectural boundaries across all subsequent turns.

2. What operational risks exist when granting an AI agent terminal shell execution permissions, and how does Claude Code manage them? Granting shell access allows an agent to invoke destructive commands (e.g., rm -rf, modifying system /etc files, or running unverified external curl scripts). Claude Code mitigates this through permission classification: read-only commands (reading files, directory listing, git status) can be configured for automatic execution, while state-modifying or potentially destructive commands (destructive git commands, file deletions, network writes) require explicit human confirmation in the terminal before running.

3. Senior scenario: an engineering team of 50 developers wants to standardize on Claude Code for daily pull request creation. How do you design the team’s repository setup and CI guardrails?

  • Repository Standardization: Create a standardized CLAUDE.md in repository roots specifying exact build commands (npm test, golangci-lint), code conventions, and testing requirements.
  • Security Boundaries: Add private environment configuration files (.env, .npmrc, private keys) to .gitignore and enforce that Claude Code approval prompts are enabled for network calls.
  • CI Validation Gate: Enforce branch protection rules in GitHub; regardless of agent self-verification, all commits pushed by Claude Code must pass automated CI pipelines and receive human peer review before merging.
  • Claude Code is Anthropic’s agentic command-line companion, powered by Claude Opus 5.5 and Sonnet 5.5.
  • Executes an autonomous loop: reads repositories, applies surgical diffs, runs test suites, and commits changes.
  • Works with any editor or environment, from local terminal windows to remote SSH sessions.
  • Ingests CLAUDE.md for deterministic project conventions, build commands, and architectural rules.
  • Compatible with the Model Context Protocol (MCP) and extensible through custom skills.