118 lines
4 KiB
Markdown
118 lines
4 KiB
Markdown
# Developing with Claude
|
|
|
|
> Run AI coding agents safely on your own machine — where the **Git repository is the memory**, not the chat history.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
## How it works
|
|
|
|
```mermaid
|
|
flowchart TB
|
|
subgraph host["💻 Your Machine"]
|
|
secrets["🔑 Secrets and Keys"]
|
|
folders["📁 Workspace Folders"]
|
|
end
|
|
|
|
subgraph container["🐳 Bounded Container — Agents Work Here"]
|
|
direction LR
|
|
claude["Claude Code"]
|
|
codex["Codex CLI"]
|
|
gemini["Gemini CLI"]
|
|
end
|
|
|
|
subgraph repo["📚 Git Repository — The Persistent Memory"]
|
|
direction LR
|
|
rules["Rules"]
|
|
state["State Docs"]
|
|
tools["Scripts"]
|
|
end
|
|
|
|
folders -->|mounts into| container
|
|
container <-->|reads before acting / writes when done| repo
|
|
secrets -.->|stays on host — never enters container| host
|
|
```
|
|
|
|
The container is bounded and disposable. The repository is permanent. Agents read the repo before every session — not the chat history — so context survives restarts, rebuilds, and parallel sessions.
|
|
|
|
---
|
|
|
|
## Why this exists
|
|
|
|
Most AI-assisted development setups share the same failure mode: context lives in chat history. The session ends, the context is gone. The next session starts blind.
|
|
|
|
This guide describes a different model:
|
|
|
|
- The **Git repo** is the operating memory — rules, state, decisions, and handoff notes all live in version-controlled Markdown
|
|
- The **Docker container** is a bounded workspace — agents can see what is mounted, not the whole machine
|
|
- **Secrets stay on the host** — never in the repo, never in the container
|
|
- **Production actions stay with the operator** — the container is powerful within its boundary; it does not have unlimited reach
|
|
|
|
Works on a laptop with no GPU, no VPN, no server. Grows as far as you want to take it.
|
|
|
|
---
|
|
|
|
## What's in this guide
|
|
|
|
| Document | What it covers |
|
|
|---|---|
|
|
| [GETTING-STARTED.md](./GETTING-STARTED.md) | Step-by-step: discover your machine, design your setup, build the baseline, orient Claude to current tooling |
|
|
|
|
---
|
|
|
|
## The five-minute version
|
|
|
|
**1. Discover your machine** — paste the discovery prompt from `GETTING-STARTED.md` into Claude. Get a `machine-discovery.md` report.
|
|
|
|
**2. Design your setup** — paste the design prompt with your discovery report into Claude Opus. Get a setup plan tailored to your hardware.
|
|
|
|
**3. Build the baseline** — workspace root, subfolders, Git repo, Docker container, Claude Code authenticated. Nothing more until it works.
|
|
|
|
**4. Orient Claude** — fetch current Anthropic docs and store them in the repo. Force Claude to read before it writes. Training data is frozen; the docs are not.
|
|
|
|
**5. Grow deliberately** — add layers only when you have a real reason.
|
|
|
|
---
|
|
|
|
## Where it grows
|
|
|
|
```mermaid
|
|
graph LR
|
|
A["💻 Laptop\nDocker + Claude Code"]
|
|
B["☁️ VPS\nGit hosting + VPN\n+ Monitoring"]
|
|
C["🏠 Home Server\nLocal AI\n+ Ollama"]
|
|
D["📱 Mobile\nRemote operator\naccess"]
|
|
|
|
A -->|stable baseline| B
|
|
B -->|stable infrastructure| C
|
|
C -->|stable local AI| D
|
|
```
|
|
|
|
Each stage is independent. None requires the next. Most of the value is in stage one.
|
|
|
|
---
|
|
|
|
## Core principles
|
|
|
|
**The repo is the memory.**
|
|
Everything important lives in Git. Agents read it before acting. Nothing is lost when a session ends.
|
|
|
|
**Secrets stay on the host.**
|
|
API keys, SSH keys, tokens — never in the repo, never in the container. Passed in at runtime.
|
|
|
|
**Production actions stay with the operator.**
|
|
Ansible runs, SSH, DNS changes — your terminal, not the container. You are always the gate.
|
|
|
|
**Persistence is designed, not assumed.**
|
|
Named Docker volumes for agent auth. A bootstrap script to verify state after rebuilds. Nothing relies on the container surviving.
|
|
|
|
**Start simple. Grow deliberately.**
|
|
Laptop first. Server when you need one. Local AI when the hardware justifies it.
|
|
|
|
---
|
|
|
|
## Getting started
|
|
|
|
→ **[Read GETTING-STARTED.md](./GETTING-STARTED.md)**
|