{"slug": "how-to-set-up-a-project-from-scratch-so-claude-code-works-at-its-best", "title": "How to Set Up a Project From Scratch So Claude Code Works at Its Best", "summary": "Anthropic's Claude Code performs best when projects are set up with a CLAUDE.md contract, a nine-step per-feature development loop, separate review models, and living Markdown boards, according to a walkthrough by an unnamed author. The setup, which requires no exotic tooling, aims to prevent context drift and improve agent performance across sessions.", "body_md": "Open a fresh repository, start a Claude Code session, and ask it to build a feature. It will. The code compiles, the tests pass, and for about twenty minutes it feels like magic. Then you ask for the next feature, and the one after that, and slowly the thing drifts — inconsistent structure, decisions relitigated every session, a reviewer that’s the same model that wrote the code, and no record of why anything is the way it is.\n\nThe reflex is to reach for a better prompt. That’s the wrong lever. A capable agent dropped into an empty repo behaves like a brilliant contractor with no brief: fast, confident, and pointed in a slightly different direction every day. What raises the ceiling isn’t a cleverer instruction — it’s giving the agent a **project it can reason about**: a contract, a loop, and a memory.\n\nThis is a walkthrough of exactly that setup. Do it once, at the start, and every session afterward gets sharper instead of noisier.\n\nMost “project setup” advice stops at a folder tree and a linter. That’s plumbing. The setup that changes how an agent performs is closer to an **operating system for the project** — the planning docs, the standards, the per-feature development loop, and the living boards that track what’s done, what’s risky, and what’s still an open question.\n\nThe distinction matters because agents don’t hold context between sessions the way a teammate does. Anything not written down is re-invented. So the whole game is to make the implicit explicit *once*, in files the agent reads first, and then keep those files honest.\n\nSeven moves get you there. None require exotic tooling — most are Markdown.\n\nThe single highest-leverage file is a CLAUDE.md at the repo root: the operating contract the agent reads before anything else. It answers, in one place, the questions an agent would otherwise guess at every session.\n\nIt should state:\n\nKeep it current. A contract that drifts from reality is worse than none, because the agent will follow the file, not your intentions. When the stack changes, the contract changes in the same commit.\n\nAd-hoc prompting produces ad-hoc results. A repeatable **per-feature development loop** turns “build me a thing” into a process you can supervise and trust. A version worth stealing has nine steps:\n\nThe rule that makes it work is the last one: **a feature isn’t done until its docs are updated.** That’s what stops the drift. The loop is written once in a strategy doc and referenced from the contract, so the agent can run it without being re-taught.\n\nSelf-review isn’t review. An agent grading its own homework will confidently miss the same blind spots twice. The fix is structural: the **review model or configuration must differ from the coder’s.** One agent writes; a different one reviews the diff, runs the security pass, and checks the work against the acceptance criteria.\n\nThis is the cheapest quality upgrade available, and it mirrors how real teams work — you don’t merge your own PR unreviewed. Bake it into the contract as a non-negotiable so it isn’t quietly skipped when you’re moving fast.\n\nChat history is not project memory. The moment a session ends, anything not written to a file is gone. Three living boards fix that, and they’re just Markdown. Two sit at the repo root; the third lives with your planning docs:\n\nThe payoff: any new session — yours or the agent’s — can read three files and know exactly where things stand, instead of reconstructing it from memory that doesn’t exist.\n\nIf you find yourself re-explaining your coding conventions, data-modeling rules, or PR checklist every session, that’s a signal to **vendor them as skills** the agent loads automatically — small, named standard folders under .claude/skills/, each holding its own SKILL.md.\n\nTwo rules keep this honest. First, name the mandatory skills (apply on every relevant change) separately from the referenced ones you invoke on demand. Second — and this is the one people skip — **if you can’t locate the real standard, write a stub that references it and flag the gap.** Don’t let the agent invent a standard to fill the hole. A flagged stub that says “TODO: real Python standard lives at X” is safe; a fabricated one that reads authoritative is a landmine. Dual-track any stub with a row in RISKS.md and open-questions.md until it's real.\n\nAutonomy without brakes is how you wake up to a force-pushed main branch. Two guardrails, stated plainly in the contract, prevent the expensive mistakes:\n\nAdd least-privilege identities and a cap on spawn/cost, and you’ve turned “the agent can do anything” — which is terrifying — into “the agent can do a lot, within rails you set” — which is useful.\n\nThe final habit is a working posture, not a file. For anything non-trivial, drive the agent through four beats: **express intent → validate a plan → let it create → verify the result.** Don’t let it write files before you’ve approved the plan. Ask when a choice changes structure; pick a sensible default and state it when it doesn’t.\n\nThis is the difference between supervising and hoping. You’re not typing every line — you’re setting intent, checking the plan against reality, and enforcing the gates. The acceptance criteria (Gherkin’s *Given/When/Then* works well) are the contract you brief the agent against, so “done” means something specific instead of “looks fine to me.”\n\nPut concretely, the setup lands as a small, legible structure:\n\n```\n<repo-root>/├── CLAUDE.md            # the contract — read first├── README.md            # overview + doc index├── STATUS.md            # living progress board├── RISKS.md             # living risk register├── .github/│   └── pull_request_template.md   # work-item ↔ branch ↔ PR traceability├── .claude/│   ├── skills/          # vendored standards (stub + flag if missing)│   └── commands/        # one per recurring loop step└── docs/    ├── planning/        # dev loop, open questions, DoR/DoD, governance    ├── strategy/        # testing, security, CI/CD, versioning    └── architecture/    # reference architecture + ADRs\n```\n\nEvery file earns its place by removing a question the agent would otherwise guess at. That’s the test for whether something belongs: does it make the implicit explicit?\n\nHere’s the part that closes the loop: this setup is itself something you can hand to Claude Code. A single **bootstrap prompt** — one you paste into a fresh repo — can interview you about your stack, governance, and standards, then generate the whole operating system: the contract, the loop, the boards, the vendored-skill stubs, and the folder tree above. Plan-first, approve, then create.\n\nTwo choices shape the output. Are you providing product requirements now, or just standing up the scaffold? And are you copying standards from a reference project you’ve already built this way, or generating them fresh? The reference-copy path is fastest and most consistent, because those files are already your team’s conventions — you’re adapting, not reinventing.\n\nEither way, the principle holds: the agent builds the operating system *with* you, up front, so every feature after that runs inside rails you both understand.\n\nIf you’d rather not start from a blank page, I’ve open-sourced exactly this — the bootstrap master prompt plus the fill-by-hand templates (contract, per-feature loop, governance rails, and living boards): [ github.com/Rajeev0814/claude-code-project-bootstrap](https://github.com/Rajeev0814/claude-code-project-bootstrap). Paste the prompt and let an agent generate it, or copy the templates and fill them in yourself.\n\nThe best content creators don’t rely on inspiration — they rely on systems. The same is true for building with AI agents. The leverage isn’t in one perfect prompt; it’s in a project the agent can reason about, remember, and be held accountable to.\n\nSet up the contract, the loop, and the boards first. Then let the agent move fast — because now, when it moves fast, it moves in the direction you actually chose.\n\nWhat’s the first thing that drifts in *your* AI-assisted projects — the structure, the decisions, or the review? I’d genuinely like to know which rail is worth adding first. Drop it in the comments.\n\n[How to Set Up a Project From Scratch So Claude Code Works at Its Best](https://pub.towardsai.net/how-to-set-up-a-project-from-scratch-so-claude-code-works-at-its-best-ae3e315ca338) was originally published in [Towards AI](https://pub.towardsai.net) on Medium, where people are continuing the conversation by highlighting and responding to this story.", "url": "https://wpnews.pro/news/how-to-set-up-a-project-from-scratch-so-claude-code-works-at-its-best", "canonical_source": "https://pub.towardsai.net/how-to-set-up-a-project-from-scratch-so-claude-code-works-at-its-best-ae3e315ca338?source=rss----98111c9905da---4", "published_at": "2026-08-10 14:01:04+00:00", "updated_at": "2026-08-10 14:17:05.945953+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-agents"], "entities": ["Anthropic", "Claude Code"], "alternates": {"html": "https://wpnews.pro/news/how-to-set-up-a-project-from-scratch-so-claude-code-works-at-its-best", "markdown": "https://wpnews.pro/news/how-to-set-up-a-project-from-scratch-so-claude-code-works-at-its-best.md", "text": "https://wpnews.pro/news/how-to-set-up-a-project-from-scratch-so-claude-code-works-at-its-best.txt", "jsonld": "https://wpnews.pro/news/how-to-set-up-a-project-from-scratch-so-claude-code-works-at-its-best.jsonld"}}