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 document_type: how-to
status: active status: active
created: 2026-04-01 created: 2026-04-01
updated: 2026-04-01 updated: 2026-04-01
tags: tags:
- agentlab - claude
- onboarding - ai-development
- getting-started - 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.* > *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: 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) 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/` 2. Create subfolders: `your-repo/`, `work-rw/`, `drop-ro/`
3. Clone this repo into `vault-repo/` 3. Initialise a Git repo inside `your-repo/` and create a `README.md`
4. Install Docker if not already present 4. Install Docker if not already present
5. Authenticate Claude Code 5. Set up a devcontainer or Docker Compose file based on the plan Claude produced
6. Run `bootstrap.sh` to verify tool state 6. Authenticate Claude Code inside the container
7. Ask Claude to read `LLM-ENTRYPOINT.md` and confirm it can navigate the repo 7. Ask Claude to describe the repo structure and confirm it can navigate it
Do not add more until this works cleanly. 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:** **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: Then do the following:
1. Fetch the current Claude Code documentation from the official Anthropic docs site 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/ 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 3. Identify any repo rules or config 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 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. 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 ## 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. 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 | | 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 | | `~/AgentLab/work-rw/` | Working files and scratch space written by agents |
| `~/.ssh/` | SSH keys — lose these and you are locked out of every server | | `~/.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 | | 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. 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. 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 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."** **"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. 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:** **Review what is open and decide what to do next:**
``` ```
Read LLM-ENTRYPOINT.md and follow the mandatory read order. Read the repo README and any state documents present.
Then tell me: what is the current system state, what is unresolved, and what is the highest-leverage thing I can work on today? 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:** **Plan a new component:**
``` ```
Read LLM-ENTRYPOINT.md and follow the mandatory read order. I want to add [component] to this repo.
I want to add [component]. Before writing anything, fetch the current documentation for every
Before writing anything, fetch the current documentation for every third-party component involved. 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. Then propose a phased plan, flag any open decisions, and list what I need to provide.
``` ```
**Understand the agent collaboration model:** **Understand the agent collaboration model:**
``` ```
Read docs/agent-handbook.md. Review any agent configuration and rules in this repo.
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. 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 | | File | Purpose | Create it when… |
|---|---| |---|---|---|
| `LLM-ENTRYPOINT.md` | Where every agent session begins — mandatory read order and environment facts | | `README.md` | Human-facing landing page — what this is, current state, key links | Day one |
| `AGENTS.md` | Cross-agent operating contract — branch model, permissions, standards | | `ENTRYPOINT.md` | Agent session startup — what to read first, environment facts, execution boundaries | Once you have more than one doc |
| `docs/system-plan.md` | Planning source of truth — what is built, what is open, what is next | | `AGENTS.md` | Operating contract for AI agents — what they can do, what requires approval | Before doing serious work with agents |
| `docs/priorities.md` | Current priority order | | `docs/system-plan.md` | Planning source of truth — what is built, what is open, what is next | When you have infrastructure to track |
| `docs/agent-handbook.md` | Shared agent onboarding and operating protocol | | `docs/open-loops.md` | Persistent backlog across sessions — so nothing falls through the cracks | When unresolved items start accumulating |
| `docs/open-loops.md` | Persistent backlog of unresolved items across all sessions | | `bootstrap.sh` | Idempotent setup script — verifies the workspace is in the expected state after rebuilds | Once your setup has more than 3 steps |
| `bootstrap.sh` | Idempotent runtime verification — run after any container rebuild | | `.claude/rules/` | Repo-level rules loaded every Claude session — safety, style, workflow | When you have patterns you keep repeating |
| `.claude/rules/` | Repo-level rules enforced for every Claude session | | `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:** **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.
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.*