docs: professional README with architecture diagrams
This commit is contained in:
parent
3aa0e0d47b
commit
c7f6eee516
1 changed files with 124 additions and 2 deletions
126
README.md
126
README.md
|
|
@ -1,3 +1,125 @@
|
|||
# developing-with-claude
|
||||
# Developing with Claude
|
||||
|
||||
Getting started with AI-native development workspaces
|
||||
> 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 & Keys\nnever enter the workspace"]
|
||||
folders["📁 Workspace Folders\nbind-mounted, always persist"]
|
||||
end
|
||||
|
||||
subgraph container[" 🐳 Bounded Container — Agents Work Here "]
|
||||
direction LR
|
||||
claude["Claude\nCode"]
|
||||
codex["Codex\nCLI"]
|
||||
gemini["Gemini\nCLI"]
|
||||
end
|
||||
|
||||
subgraph repo[" 📚 Git Repository — The Persistent Memory "]
|
||||
direction LR
|
||||
rules["Rules &\nBoundaries"]
|
||||
state["System\nState"]
|
||||
tools["Scripts\n& Tools"]
|
||||
end
|
||||
|
||||
folders -->|mounts into| container
|
||||
container <-->|"reads before acting\nwrites when done"| repo
|
||||
secrets -.->|stays here,\nnever shared| 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 have 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\n―――――――\nDay 1"]
|
||||
B["☁️ VPS\nForgejo · WireGuard\nPrometheus · Loki\n―――――――\nWhen needed"]
|
||||
C["🏠 Home Server\nLocal AI · Ollama\nOpen WebUI\n―――――――\nWhen justified"]
|
||||
D["📱 Mobile\nRemote operator\naccess\n―――――――\nWhen ready"]
|
||||
|
||||
A -->|stable baseline| B
|
||||
B -->|stable infra| 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)**
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) — use it, adapt it, share it with attribution.
|
||||
|
|
|
|||
Loading…
Reference in a new issue