.mcp.json Template for Team MCP Servers
A project .mcp.json with one stdio server and one HTTP server, with secrets and paths kept in environment variables.
- Claude Code
2 files5.1 KB.zip
A 70-line starter CLAUDE.md: project, stack, commands, hard rules, how to verify work and what not to do.
By Matthews WongUpdated Checked against Claude Code 2.1.323 docs
Key takeaway
A starter CLAUDE.md you copy to the root of a repository and edit. It has eight short sections with bracketed placeholders: what the project is, stack, commands, directory map, hard rules, conventions, how to verify work and what not to do. Claude Code reads the file at the start of every session, so the template stays near 70 lines and leaves long procedures to skills.
Exactly what the download contains. Read it first, then copy or download.
# [Project name]
<!--
Starter CLAUDE.md. Save it at the repository root, replace every [bracketed]
part, and delete any section that has nothing true to say. Claude reads this
file at the start of every session, so each line should earn its place.
Comments like this one are for people; delete them when you are done.
-->
## What this project is
[One or two sentences: what it does, who uses it, and where it runs.]
## Stack
- Language and runtime: [for example TypeScript on Node.js 22]
- Framework: [name and major version]
- Data: [database, ORM or query layer]
- Tests: [test runner]
- Deploy: [how and where it ships]
## Commands
```bash
[dev command] # start the app locally
[test command] # run the tests; single file: [how]
[lint command] # lint and format check
[build command] # production build
```
## Directory map
```text
[src/app/] [routes or entry points]
[src/lib/] [shared logic]
[src/db/] [schema and migrations]
[tests/] [where tests live and how they are named]
```
## Hard rules
These break the build or production when ignored.
1. [Rule, and what fails when it is broken]
2. [Rule, and what fails when it is broken]
3. Never commit secrets. Configuration comes from [where].
## Conventions
- [Naming: files, functions, database columns]
- [Imports: the alias or the order to use]
- [Errors: how they are raised, logged and returned]
- Follow the patterns in the file you are editing before adding a new one.
## How to verify work
- Read a file before editing it, and the files that call it.
- For a bug, reproduce it first, then fix it, then run the same reproduction.
- After each change run `[test command]` and `[lint command]`, and report
the real output. Do not say it works without running it.
- [Any check specific to this project, such as a type check or a migration
dry run]
## What not to do
- Do not refactor or rename things outside the task unless asked.
- Do not add a dependency without asking.
- Do not edit [generated files or folders]; change [their source] instead.
- Do not commit or push unless asked. One logical change per commit.
- [Anything this team has been burned by before]
Download the file and save it as CLAUDE.md in the root of your repository. Claude Code also accepts .claude/CLAUDE.md. Commit it so the whole team shares the same instructions.
Replace the four command placeholders with the exact dev, test, lint and build commands. These are the lines Claude uses most, and the ones it cannot reliably guess.
List the few things that break the build or production, each with what fails. Be specific: a rule that names the file and the check is followed more consistently than a general one.
Remove any section or bullet that has nothing true to say, and delete the comment at the top. An empty placeholder costs context in every session and tells Claude nothing.
Start Claude Code in the repository and run /memory, which lists your CLAUDE.md files, and confirm the project file is there. Then ask for a small change and watch whether it runs your test command without being told.
Claude reads CLAUDE.md at the start of every session, and the docs set a target of under 200 lines per file because longer files use more context and reduce adherence. The template is about 70 lines, which leaves room for your own rules.
Dev, test, lint and build sit together with a comment each, including how to run a single test file. Claude can copy the exact command instead of working it out from package files.
Things that break the build are numbered and say what fails. Style preferences go under Conventions. Keeping them apart shows which lines are not negotiable.
Read before editing, reproduce a bug before fixing it, run the tests after each change and report the real output. These working habits are filled in already, because they apply to almost any repository.
The how-to note at the top is a block-level HTML comment. Claude Code strips such comments before the file reaches Claude's context, so you can keep maintainer notes there without spending tokens on them.
Short answers before you download it.
Free lessons and articles on this site that explain the ideas behind it.
Primary sources checked on the research date. Follow them for the current version.
A project .mcp.json with one stdio server and one HTTP server, with secrets and paths kept in environment variables.
2 files5.1 KB.zip
A planning prompt that covers business, domain, tech design and steps, then lists the decisions it needs from you.
1 file2.3 KB.md
A stdio MCP server with two tools, a resource, a prompt and a smoke test, on the v2 SDK.
9 files11.1 KB.zip