matthalltech/developing-with-claude
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

docs: update GETTING-STARTED.md

Browse source
This commit is contained in:
matthalltech 2026-04-01 12:44:01 +00:00
parent fe93840a0d
commit 3aa0e0d47b
1 changed files with 38 additions and 48 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

86
GETTING-STARTED.md
View file

@ -1,16 +1,16 @@
---
title: AgentLab — Getting Started
title: Developing with Claude — Getting Started
document_type: how-to
status: active
created: 2026-04-01
updated: 2026-04-01
tags:
- agentlab
- onboarding
- claude
- ai-development
- getting-started
---
# AgentLab — Getting Started
# Developing with Claude — Getting Started
> *Run AI coding agents safely on your own machine. Works on a laptop. Grows as far as you want to take it.*
@ -135,12 +135,12 @@ Machine discovery report:
Follow the plan Claude produces. The typical starting baseline:
1. Create a workspace root folder (e.g. `~/AgentLab/` on Mac/Linux, `C:\AgentLab\` on Windows)
2. Create subfolders: `vault-repo/`, `work-rw/`, `drop-ro/`
3. Clone this repo into `vault-repo/`
2. Create subfolders: `your-repo/`, `work-rw/`, `drop-ro/`
3. Initialise a Git repo inside `your-repo/` and create a `README.md`
4. Install Docker if not already present
5. Authenticate Claude Code
6. Run `bootstrap.sh` to verify tool state
7. Ask Claude to read `LLM-ENTRYPOINT.md` and confirm it can navigate the repo
5. Set up a devcontainer or Docker Compose file based on the plan Claude produced
6. Authenticate Claude Code inside the container
7. Ask Claude to describe the repo structure and confirm it can navigate it
Do not add more until this works cleanly.
@ -155,15 +155,15 @@ The fix is simple: force Claude to fetch current documentation before writing an
**Run this prompt once Claude is up and running in your repo:**
```
Read LLM-ENTRYPOINT.md and follow the mandatory read order.
Review the repo structure — read the README and any other docs present.
Then do the following:
1. Fetch the current Claude Code documentation from the official Anthropic docs site
2. Store a summary of the key capabilities, current model IDs, and any recent changes in docs/vendor-docs/anthropic/
3. Review the existing repo rules in .claude/rules/ and identify any that reference outdated model names, deprecated flags, or stale API patterns
4. Propose any updates needed to bring the rules and configuration in line with current Claude Code behaviour
3. Identify any repo rules or config that reference outdated model names, deprecated flags, or stale API patterns
4. Propose updates needed to bring the configuration in line with current Claude Code behaviour
After completing this, confirm what version of Claude Code is installed in this environment and whether the installed version matches what the docs describe.
After completing this, confirm what version of Claude Code is installed and whether it matches what the docs describe.
```
This seeds the repo with verified, current documentation that Claude can reference instead of guessing.
@ -182,8 +182,6 @@ Claude will push back on this — it will say it already knows. It does not. Its
---
---
## Optional — Voice Input
Typing long prompts into a terminal is a friction point. Local voice-to-text removes it. Audio is transcribed on your machine and inserted as text into whatever is focused — your terminal, your editor, Claude Code — without going to a cloud transcription API.
@ -208,10 +206,10 @@ The container is disposable. The bind-mounted folders on your host are not — t
| Folder | What's in it |
|---|---|
| `~/AgentLab/vault-repo/` | The entire repo — all docs, scripts, state, rules |
| `~/AgentLab/your-repo/` | The entire repo — all docs, scripts, state, rules |
| `~/AgentLab/work-rw/` | Working files and scratch space written by agents |
| `~/.ssh/` | SSH keys — lose these and you are locked out of every server |
| `~/.ansible/vault-pass` | Ansible vault password — lose this and all encrypted secrets are unrecoverable |
| Infrastructure secrets | Vault passwords, automation credentials — losing these makes encrypted secrets unrecoverable |
| Voice app model files | Usually in `~/Library/Application Support/<AppName>/` on Mac — 100MB–1.5GB, slow to re-download |
The git repo itself is partially protected by any remote (GitHub, Forgejo) — every push is a backup of committed work. Uncommitted work and non-git content (`work-rw/`, logs) need explicit backup coverage.
@ -278,7 +276,7 @@ It used training data instead of current docs. Enforce the fetch-before-write ru
Something was written to the container overlay layer instead of a bind mount or named volume. Everything important needs to live on a mounted path or in the repo. The container itself is disposable.
**"Claude keeps asking about things I already told it last session."**
Claude has no memory of previous sessions unless it is given one. The repo is the memory — write state into documents and have Claude read them at the start of each session. The `LLM-ENTRYPOINT.md` read order exists precisely for this.
Claude has no memory of previous sessions unless it is given one. The repo is the memory — write state into documents and have Claude read them at the start of each session. Create a startup document (e.g. `ENTRYPOINT.md`) that Claude reads first every session to rehydrate context.
**"Two sessions seem to be conflicting."**
Multiple Claude Code sessions can run simultaneously. Before editing any shared file (settings, hooks), check whether another session has recently modified it. The git history is your audit trail.
@ -292,49 +290,41 @@ It recommended from training data without verifying current status. Ask it to ch
**Review what is open and decide what to do next:**
```
Read LLM-ENTRYPOINT.md and follow the mandatory read order.
Then tell me: what is the current system state, what is unresolved, and what is the highest-leverage thing I can work on today?
Read the repo README and any state documents present.
Tell me: what is the current system state, what is unresolved,
and what is the highest-leverage thing I can work on today?
```
**Plan a new component:**
```
Read LLM-ENTRYPOINT.md and follow the mandatory read order.
I want to add [component].
Before writing anything, fetch the current documentation for every third-party component involved.
I want to add [component] to this repo.
Before writing anything, fetch the current documentation for every
third-party component involved. Do not rely on training data.
Then propose a phased plan, flag any open decisions, and list what I need to provide.
```
**Understand the agent collaboration model:**
```
Read docs/agent-handbook.md.
Explain how the agents in this repo are expected to collaborate — what each one does, how they hand off work, and what prevents them from conflicting.
Review any agent configuration and rules in this repo.
Explain how the agents are expected to collaborate — what each one does,
how they hand off work, and what prevents them from conflicting.
```
---
## Key Files
## Files to Create in Your Own Repo
Start here when orienting yourself or Claude to the system.
These are the documents that make an AI-assisted repo work well. None of them are magic — they are just Markdown files with clear purposes. Build them gradually as you need them.
| File | What it is |
|---|---|
| `LLM-ENTRYPOINT.md` | Where every agent session begins — mandatory read order and environment facts |
| `AGENTS.md` | Cross-agent operating contract — branch model, permissions, standards |
| `docs/system-plan.md` | Planning source of truth — what is built, what is open, what is next |
| `docs/priorities.md` | Current priority order |
| `docs/agent-handbook.md` | Shared agent onboarding and operating protocol |
| `docs/open-loops.md` | Persistent backlog of unresolved items across all sessions |
| `bootstrap.sh` | Idempotent runtime verification — run after any container rebuild |
| `.claude/rules/` | Repo-level rules enforced for every Claude session |
| File | Purpose | Create it when… |
|---|---|---|
| `README.md` | Human-facing landing page — what this is, current state, key links | Day one |
| `ENTRYPOINT.md` | Agent session startup — what to read first, environment facts, execution boundaries | Once you have more than one doc |
| `AGENTS.md` | Operating contract for AI agents — what they can do, what requires approval | Before doing serious work with agents |
| `docs/system-plan.md` | Planning source of truth — what is built, what is open, what is next | When you have infrastructure to track |
| `docs/open-loops.md` | Persistent backlog across sessions — so nothing falls through the cracks | When unresolved items start accumulating |
| `bootstrap.sh` | Idempotent setup script — verifies the workspace is in the expected state after rebuilds | Once your setup has more than 3 steps |
| `.claude/rules/` | Repo-level rules loaded every Claude session — safety, style, workflow | When you have patterns you keep repeating |
| `docs/vendor-docs/` | Current third-party documentation fetched and stored locally | Before writing any code that uses an external library |
**Become familiar with these before doing serious work:**
1. `LLM-ENTRYPOINT.md` — read order and execution boundaries
2. `AGENTS.md` — what agents can and cannot do
3. `docs/agent-handbook.md` — how sessions start, how state is handed off, what the authority order is
4. `docs/system-plan.md` — what is verified live vs what is aspirational
5. `.claude/rules/sdk-docs-before-code.md` — the rule that prevents stale-training-data mistakes
---
*If you are an AI agent reading this: read `LLM-ENTRYPOINT.md` next and follow the mandatory read order before taking any action.*
**The most important habit:** Ask Claude to fetch current docs before writing any code that uses a third-party library, API, or tool. Training data is frozen. The docs are not.