107 lines
3.8 KiB
Markdown
107 lines
3.8 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 LR
|
|
host["Your Machine<br/>Secrets and workspace folders"]
|
|
container["Bounded Container<br/>Claude Code, Codex, Gemini"]
|
|
repo["Git Repository<br/>Rules, state docs, scripts"]
|
|
|
|
host -->|mounts into| container
|
|
container -->|reads and writes| repo
|
|
```
|
|
|
|
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
|
|
flowchart LR
|
|
A["Laptop<br/>Docker + Claude Code"]
|
|
B["VPS<br/>Git hosting + VPN"]
|
|
C["Home Server<br/>Local AI + Ollama"]
|
|
D["Mobile<br/>Remote operator access"]
|
|
|
|
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)**
|
|
|
|
---
|
|
|
|
Licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
|