How to set up a Claude Project so it works from the first message

This is a guide, not a tested recipe. Projects can’t run through our headless test runner, so nothing below has a pass/fail table. It comes from the receiving end: it’s written from what a Claude sees when it starts work inside a Project, and what it wishes it had been given.

What Claude actually gets

When Claude starts a task in a Project, it doesn’t remember your last conversation. It reads, in this order of usefulness:

1. The project instructions you wrote.
2. The repositories and files you linked.
3. Project memory: short notes Claude saved earlier about decisions, preferences and facts.
4. Connected tools (GitHub, your host, your newsletter, your database) that you switched on.
5. Your message.

Anything not in that list, Claude has to guess or ask. Your job in setup is to make guessing unnecessary. Everything below follows from that.

Step 1: Write the instructions as a briefing, not a manual

You do: open the project instructions and write 10 to 25 lines covering the five things below.

Claude needs:

• What the project is, in two sentences. “CodeTwig.dev: a site of tested Claude Code recipes plus a weekly newsletter.” Claude uses this to decide what counts as on-topic and what tone to write in.
• Who you are to it. Owner, solo builder, a team? “Victor owns this and approves anything public” tells Claude whose word is final.
• What it may do without asking, and what needs a yes. This is the most useful paragraph you can write. Example: “Edit code and open draft PRs freely. Ask before merging, publishing, sending email, or spending money.”
• Hard rules and naming. Brand names to avoid, words you never use, the model you want for which job.
• How you want answers. Short or detailed, bullets or prose, “lead with the answer”.

Leave out what Claude can read from the repo (file layout, language, framework). Instructions that repeat the code go stale and crowd out the rules that matter.

Test it: start a thread and ask “what do you know about this project and what are you allowed to do without asking?” If the answer surprises you, fix the instructions, not the answer.

Step 2: Link the repo, and only the repo you mean

You do: add the repository (or repositories) the work lives in. Give access to the specific repo, not your whole account.

Claude needs:

• Read and write access, stated honestly. Claude can only touch repositories you linked. If you want pull requests, make sure your GitHub account can push to that repo and the Claude GitHub app is installed on it. If it can’t, Claude will tell you it’s blocked rather than work around it.
• A branch rule. Say whether Claude pushes to main, or only opens pull requests. For anything that deploys on push, choose pull requests.
• A README that says how to run things. The two commands that matter most are “how do I run the tests” and “how do I build”. If they’re in the README, Claude uses them. If not, it spends your time finding out.

Step 3: Put in files only when they are the source of truth

You do: upload the few files Claude would otherwise ask you for: a brand guide, a spec, a CSV, the export from last month.

Claude needs:

• Files with names that say what they are, such as brand-voice.md, not final_v3.docx.
• One current version. Two similar files makes Claude pick one without telling you.
• A line in the instructions pointing at them. “Pricing lives in pricing.csv; treat it as correct.” Otherwise Claude may never open it.

Don’t upload things just in case. A short list of files Claude reads every time beats a large pile it skims.

Step 4: Connect tools for the jobs you’ll actually ask for

You do: switch on the connectors your real tasks need and nothing else. A site might need GitHub and the newsletter tool. A game might need GitHub and the host.

Claude needs:

• The least access that works. If a task only reads analytics, connect it read-only if the tool allows.
• Secrets kept out of chat. Put API keys in the service’s own secret store (an environment secret, the host’s dashboard). Never paste a key into a message or the instructions. Claude doesn’t need to see it; the running service does.
• Your say-so on outward actions. Connecting a tool lets Claude use it. Whether Claude may send the email or deploy the site is a separate decision, and belongs in the instructions from Step 1.

Step 5: Give it a first task that proves the setup

You do: don’t start with the big ask. Start with a small real task that touches every piece: read the repo, change one thing, open a draft PR.

Claude needs, in the message:

• The goal, not the steps. “The signup form should show an error when the email is invalid” beats “edit line 40”.
• What done looks like. “Tests pass and the form works at phone width.”
• Where it should stop. “Open a draft PR and tell me; don’t merge.”
• Anything you already decided. If you’ve ruled out an approach, say so once so it isn’t re-proposed.

If this first task goes smoothly, the setup works. If Claude asks a question, that’s a gap: answer it, then add the answer to the instructions so nobody gets asked twice.

Step 6: Let memory carry what you tell it twice

You do: the first time you correct Claude on a preference (“keep replies short”), or make a decision (“we chose Cloudflare”), tell it to remember. Check the notes now and then and delete any that are wrong.

Claude needs:

• Reasons, not just rules. “Avoid ‘Claude’ in the brand name because of trademark risk” lets Claude handle cases you didn’t list.
• Corrections, as you give them. Memory is how a correction survives into the next thread.
• Nothing sensitive. Memory may be shared with everyone in the project. Don’t ask it to store passwords or keys.

Instructions are for rules that never change; memory is for what you learn as you go.

The checklist

1. Instructions: what it is, who decides, what needs a yes, hard rules, answer style.
2. Repo linked with push access and a branch rule.
3. Only the files Claude should treat as truth, named clearly and pointed at.
4. Only the connectors you’ll use; secrets in the service, not in chat.
5. A small first task with a goal, a definition of done, and a stopping point.
6. Corrections and decisions saved to memory, with the reason.

Mistakes we see most

• Instructions that describe the code. Claude can read the code. Describe the decisions behind it.
• No “ask first” list. Without one, Claude has to guess between over-asking and over-doing. Name the few actions that need your yes.
• Everything connected. More tools means more ways to act in places you didn’t mean.
• Starting with the big task. A tiny first task finds the gaps for ten minutes of your time instead of an hour.
• Treating the first answer as final. If Claude assumed something wrong, fix the instruction that let it assume.