# ADR 012: Claude Code

- HTML version: https://robbiepalmer.me/projects/personal-site/adrs/012-claude-code
- Project: Personal Site (https://robbiepalmer.me/projects/personal-site.md)
- Status: Accepted
- Date: 2025-10-19

# Context

To maintain high velocity as a solo developer ("Maximize Velocity"), I need an intelligent coding partner capable of:

1. **Deep Reasoning**: Solving architectural problems, not just autocompleting lines.
2. **Breadth**: Executing multi-file refactors and understanding the entire repository context.
3. **Agentic Behavior**: The ability to run commands, read files, and iterate on errors autonomously.

# Decision

I will use **[Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)** (Anthropic's agentic coding interface) as my primary autonomous coding tool—the foundation of [LLM-Optimized](/projects?tab=philosophy#llm-optimized) development.

This involves committing to its specific configuration infrastructure:

* `.claude/` directory for tool-specific settings.
* `CLAUDE.md` for Claude Code discovery, importing the shared project context and architectural guidelines from `AGENTS.md`.

# Alternatives

## IDE Agents (Cursor / Windsurf)

* **Pros**: Best-in-class IDE integration.
* **Cons**: Primarily text-editing interfaces. A CLI-based agent loop is often more efficient for batch tasks or "fire and forget" delegation while I work on something else.

## Other Agents (Juni, Augment Code)

* **Juni**: Focuses on data integration and structured workflows.
* **Augment Code**: Optimizes for extreme speed and enterprise context.
* **Reasoning**: While these are strong competitors, **Claude Code** provides the native, unmediated experience with the specific models (Claude 4.5 Sonnet, Opus) that I find most effective for complex reasoning tasks.

## Standardized Config (`AGENTS.md`)

* **Pros**: Open standard for defining agent context, avoiding tool-specific files.
* **Cons**: At the time of this decision, Claude Code relied on its tool-specific context file for native loading. The repository now preserves native discovery through `CLAUDE.md` while sharing the actual instructions through `AGENTS.md`.

*Note: **Antigravity** is not considered in this ADR as it is a newer development than when this decision was originally made.*

# Consequences

### Pros

* **Velocity**: I can ship features significantly faster by delegating implementation details.
* **Context Management**: Centralizing project knowledge in `AGENTS.md` ensures coding agents stay aligned with the project's evolving architecture; `CLAUDE.md` imports it for Claude Code.
* **Synergy**: Necessitates robust testing \[ADR 008] and review \[ADR 009] to verify the agent's output.

### Cons

* **Vendor Lock-in**: I am building up project context and "prompt engineering" specifically in `.claude` configuration files. migrating to another agent would require porting this context.
* **Verification Overhead**: AI writes code fast, but it can also write bugs fast. "Trust but verify" becomes the dominant mode of work.

---

Markdown index of this site: https://robbiepalmer.me/llms.txt