Templates for AI projects: the bootstrap files that save hours

Every new AI-assisted project needs the same scaffolding. Without templates, you write it fresh each time and inevitably forget pieces. With templates, you copy-customize in five minutes.

This post documents the seven bootstrap templates we keep in ~/dev/_shared/templates/ and what each one does.

The seven templates

Template 1: claude-md-project.md

A starter project CLAUDE.md.

# <PROJECT NAME>

## Build & test
- <main build command>
- <test command>
- <commit signing requirement, if any>

## Architecture
- <directory>: <one-line purpose>
- <directory>: <one-line purpose>

## Conventions
- Indent: <4 spaces / 2 spaces / tabs>
- Naming: <camelCase / snake_case>
- Branches: feat/, fix/, docs/

## Rules
- <Concrete rule 1>
- <Concrete rule 2>

## Out of scope
- <thing not to suggest>
- <thing in a different module>

## Hot files
- src/foo.ts — <purpose, ~LOC>

Customize the placeholders, save as <project>/CLAUDE.md, commit. Done.

See the CLAUDE.md post for what to put in each section.

Template 2: claude-md-session.md

A starter session CLAUDE.md.

# Session: <verb-noun> — <date>

## Goal
<One paragraph: what we're doing this run>

## Out of scope
- <thing not in this run>

## Constraints
- <command to run before commits>
- <branch policy>

Five sections, ~15 lines. The contract for one specific AI run.

Template 3: gitignore-ai-additions

Lines to add to a project's .gitignore for AI workflows:

# AI / agent runtime
.claude/
.omc/
.cursor/
.aider*/
*.aider.chat.history.md

# Session-local working dirs
.session/
_session/

# AI-generated artifacts (don't commit unless intentional)
artifacts/
generated/
*.ai-output.md

These prevent accidentally committing agent state to the repo. Add to your project's .gitignore early.

Template 4: init-session.sh

Shell script to bootstrap a new session directory:

#!/bin/bash
# usage: init-session.sh <verb-noun>
# creates ~/dev/sessions/$(date +%Y-%m-%d)-<verb-noun>/ with the basics

set -e

SESSION_NAME="$1"
if [ -z "$SESSION_NAME" ]; then
  echo "Usage: $0 <verb-noun>" >&2
  exit 1
fi

DATE=$(date +%Y-%m-%d)
SESSION_DIR="$HOME/dev/sessions/$DATE-$SESSION_NAME"
TEMPLATE_DIR="$HOME/dev/_shared/templates"

mkdir -p "$SESSION_DIR"/{artifacts,notes}
cp "$TEMPLATE_DIR/claude-md-session.md" "$SESSION_DIR/CLAUDE.md"
sed -i '' "s/<verb-noun>/$SESSION_NAME/" "$SESSION_DIR/CLAUDE.md"
sed -i '' "s/<date>/$DATE/" "$SESSION_DIR/CLAUDE.md"
touch "$SESSION_DIR/notes.md"

echo "Created: $SESSION_DIR"
echo "Edit CLAUDE.md to fill in goal, scope, constraints."

Usage:

init-session.sh auth-rewrite
# Creates ~/dev/sessions/2026-04-22-auth-rewrite/

Now the session is structured before you've even started.

Template 5: prompts/code-review-strict.md

A reusable prompt for code review:

---
intent: Strict code review with defect detection
last-updated: 2026-04-22
---

You are reviewing a pull request. Read the diff carefully, then produce a
severity-rated list (P0/P1/P2) of findings. For each finding:

1. Quote the offending line(s) in a fenced block
2. Explain the defect in one sentence
3. Suggest the smallest fix that addresses it
4. If the finding is a stylistic preference (not a defect), prefix with [STYLE]

Do not list things that are correct. Do not summarize the PR.

This is one of ~20 prompts in ~/dev/_shared/prompts/. See the prompt library post for the full pattern.

Template 6: worktree-init.sh

Shell script to spawn a worktree for a session:

#!/bin/bash
# usage: worktree-init.sh <repo-path> <branch> <worktree-target>
# creates a git worktree at the target path on the given branch

set -e

REPO="$1"
BRANCH="$2"
TARGET="$3"

if [ -z "$REPO" ] || [ -z "$BRANCH" ] || [ -z "$TARGET" ]; then
  echo "Usage: $0 <repo-path> <branch> <worktree-target>" >&2
  exit 1
fi

cd "$REPO"

# Create branch if it doesn't exist
git rev-parse --verify "$BRANCH" >/dev/null 2>&1 || git branch "$BRANCH"

git worktree add "$TARGET" "$BRANCH"

echo "Worktree at: $TARGET (branch: $BRANCH)"

Usage:

worktree-init.sh ~/dev/repos/main-app feat/auth-jwt ~/dev/sessions/2026-04-22-auth-rewrite/repo

Combined with init-session.sh, you get full session + worktree + branch in two commands.

Template 7: notes-template.md

A starter notes.md for a session:

# Notes — <session name>

## What I tried
- 

## What worked
- 

## What didn't
- 

## Open questions
- 

## TODO
- [ ] 

Filled in as you go. Becomes the session log. Useful for retrospection or for handing off to a teammate.

Where to keep templates

~/dev/_shared/
├── templates/
│   ├── claude-md-project.md
│   ├── claude-md-session.md
│   ├── gitignore-ai-additions
│   ├── init-session.sh
│   ├── notes-template.md
│   └── worktree-init.sh
├── prompts/
│   └── (your prompt library)
└── references/
    └── (long-lived reference docs)

~/dev/_shared/ is version-controlled in its own repo. Sync across machines.

In your global ~/.claude/CLAUDE.md:

## Reusable assets
- Templates: ~/dev/_shared/templates/
- Prompts: ~/dev/_shared/prompts/
- References: ~/dev/_shared/references/

When starting a new project, use templates/claude-md-project.md as starting point.
When starting a new session, run templates/init-session.sh.

Now any agent in any session knows where to find them.

How to introduce templates without it being painful

Don't try to make all seven on day 1. Phased adoption:

Day 1: claude-md-session.md + init-session.sh

These are the highest-leverage. Five-line shell script + 15-line markdown template = 90% of the value.

Week 1: claude-md-project.md

When you're starting a new project, use the project template. Existing projects can adopt by writing CLAUDE.md retrospectively.

Week 2: prompts library

Extract the 5-10 prompts you reuse weekly. Save as files in ~/dev/_shared/prompts/. Reference by path in session CLAUDE.md.

Month 1: worktree-init.sh + notes-template.md

When parallelism becomes real, wire up the worktree script. Notes template comes naturally as you start writing notes.

Month 2: gitignore-ai-additions

When you accidentally commit .cursor/ once, you'll add the gitignore template. Until then it's optional.

Maintenance

Templates aren't write-once. Three signals to update:

"I keep editing this in the same way after copying"

If 80% of your CLAUDE.md sessions add a "use TypeScript strict" line, add it to the template. The template should reflect your defaults.

"The template references an old tool / pattern"

When you migrate (Yarn → pnpm, JS → TS, sync → async), update templates. Stale templates teach old patterns.

"I forget to use the template"

If a template isn't in your habit, the friction is too high. Review: is it discoverable? Is the script easy to type? Adjust until use is automatic.

What templates DON'T do

For honesty:

Templates don't replace thinking

Each session still needs scope/constraints filled in honestly. Copying the template and not customizing it gives you a generic CLAUDE.md the agent will skim.

Templates don't fix bad patterns

If your CLAUDE.md template is generic, the templated CLAUDE.md will be too. Fix the template.

Templates don't transfer between people perfectly

A template that fits your workflow won't fit a teammate's. Templates are personal. Document them in your dotfiles repo's README, but don't expect 1:1 transfer.

A worked example

Starting a new session for "rewrite-auth":

$ init-session.sh rewrite-auth
Created: /Users/me/dev/sessions/2026-04-22-rewrite-auth
Edit CLAUDE.md to fill in goal, scope, constraints.

$ cd ~/dev/sessions/2026-04-22-rewrite-auth
$ vim CLAUDE.md   # fill in 5 lines
$ worktree-init.sh ~/dev/repos/main-app feat/auth-jwt ~/dev/sessions/2026-04-22-rewrite-auth/repo
Worktree at: /Users/me/dev/sessions/2026-04-22-rewrite-auth/repo (branch: feat/auth-jwt)

$ cmux create rewrite-auth --dir ~/dev/sessions/2026-04-22-rewrite-auth
$ cmux attach rewrite-auth
$ claude-code
> Read CLAUDE.md and start the auth rewrite as scoped.

Total: 5 commands, ~3 minutes. Without templates, this would be 15-20 minutes of fiddly directory creation, file editing, branch setup.

File-manager integration

mq-dir users: pin ~/dev/_shared/templates/ to a Favorites entry. When you start a session, you can drag files into the new session directory or open the templates pane to peek before customizing.

The CMUX sidebar will show the new session as soon as cmux create runs.

Verdict

Templates are the lowest-effort, highest-impact AI workflow optimization. Spend an afternoon making your seven; save hours per week thereafter.

The seven we use:

1. claude-md-project.md
2. claude-md-session.md
3. gitignore-ai-additions
4. init-session.sh
5. prompts/code-review-strict.md (and ~20 others)
6. worktree-init.sh
7. notes-template.md

All in ~/dev/_shared/templates/, version-controlled, referenced from global CLAUDE.md.

If you start with just two — claude-md-session.md + init-session.sh — you'll add the others as you feel the friction. The investment is small; the return is daily.

mq-dir is free, MIT, and pairs cleanly with this workflow (the templates pane is just another sidebar favorite).