The first five walls of Claude Code.

# CLAUDE.md starter

Save this as `CLAUDE.md` in the top folder of your project. Claude Code reads it
at the start of every session, before your first message.

Replace everything in square brackets. Delete every line you do not need. A
short file that gets followed beats a thorough one that gets skipped.

Anthropic's guidance is to target under 200 lines, because longer files reduce
adherence. The sharper test for every single line below: **would removing this
line cause Claude to make a mistake?** If not, cut it. (The test is ours; the
200-line target is Anthropic's.)

---

## What this project is

[One or two sentences. What the work is, who it is for, what "done" looks like.]

## How I want you to work

- [Ask before X. For example: ask before creating a new file rather than editing
  an existing one.]
- [Show me Y before doing it. For example: show me the plan before you start
  changing things.]
- [Never Z without checking with me. For example: never send anything to anyone.]

## Words that mean something specific here

- **[Your term]**: [what it means in this project, and what it is NOT]
- **[Your term]**: [what it means in this project, and what it is NOT]

Ambiguous vocabulary is the single most common reason a capable model gives a
confidently wrong answer. If two words in your world could be confused, define
both here.

## Where things live

- [folder or file]: [what belongs there]
- [folder or file]: [what belongs there]

## How I want things written

- [Tone, format, or style rules. For example: plain language, no jargon.]
- [Formatting rules. For example: dates as YYYY-MM-DD.]

## Things that have gone wrong before

- [The mistake, and the rule that prevents it.]

Only keep entries here that have actually happened. This section is where these
files get bloated, and a bloated file is one Claude follows less reliably.

---

## Maintaining this file

Treat it like anything else you own: review it when something goes wrong, prune
it regularly, and check whether a change actually shifted the behaviour.

Two symptoms and what they usually mean:

- **A rule keeps getting broken.** The file is probably too long and that rule is
  getting lost. Cut other things.
- **Claude asks you something this file already answers.** The wording is
  probably ambiguous. Rewrite that line, do not add a second one.

If a rule must hold every single time, with no exceptions, this file is the
wrong home for it. This file is a request. A hook is enforcement.

---
name: weekly-update
description: Writes the weekly status update from this week's notes, following the house format of wins, risks, and asks. Use when the user says "write the weekly update", "draft my status note", "what do I send the team this week", or asks for a summary of the week's progress. SKIP for a one-off summary of a single document, and for anything that gets sent without the user reading it first.
---

# Weekly update

## Before you start

Read `CLAUDE.md` for the vocabulary. If the notes folder is empty or covers a
different week than the user asked for, say so and stop. Do not invent progress.

## Steps

1. Gather every note file changed in the last seven days.
2. Sort what you find into three buckets, and only these three:
   - **Wins**: things that finished. Not things that progressed.
   - **Risks**: things that could stop a win from happening. Each one needs a
     named owner or it is not a risk, it is a worry.
   - **Asks**: decisions or approvals needed from someone else, each with the
     name of the person and the date it is needed by.
3. Anything that fits none of the three buckets gets left out. A weekly update is
   not a diary.
4. Write it in the format below. Six bullets maximum in total. If there are more
   than six, the extra ones were not important enough for this update.
5. Show it to the user. Never send anything.

## Format

```
Week of [date]

Wins
- [what finished, and why it mattered]

Risks
- [what could go wrong] (owner: [name])

Asks
- [what you need] from [name], by [date]
```

## Rules

- Plain language. If a sentence needs a glossary, rewrite the sentence.
- Every claim traces to a note. If you cannot point at the note, cut the line.
- No filler. "Continued work on X" is not a win and does not go in.
- If a week genuinely had no wins, say that. A short honest update is worth more
  than a padded one, and padding is what teaches people to stop reading these.

---

## How to adapt this

Three things make a skill fire at the right moment and stay useful:

1. **The description at the top is the whole selection mechanism.** Claude reads
   only the name and description when deciding whether to use this. It has not
   read a word of the body. Write the description in third person, say what the
   skill does AND when to use it, and include the actual phrases you would type.
2. **The SKIP line matters as much as the trigger.** It is how you stop three
   similar skills from all looking equally plausible.
3. **Keep the body short and the steps specific.** This is a procedure, not an
   essay. The more exact the sequence, the more consistent the result.

#!/usr/bin/env bash
# PreToolUse hook: refuse to write a SQL file that uses SELECT *.
#
# WHY THIS EXISTS
# A skill can say "never SELECT *" and the model still slips. A skill is a
# request. This hook is enforcement: it reads what is about to be written and
# says no if the query uses SELECT *, so the rule holds whether or not the model
# remembered it.
#
# INSTALL
#   1. Save as .claude/hooks/no-select-star.sh, then: chmod +x .claude/hooks/no-select-star.sh
#   2. Add it to .claude/settings.json under hooks.PreToolUse with matcher "Write|Edit".
#
# TEST WITHOUT CLAUDE
#   echo '{"tool_input":{"file_path":"qry_signups.sql","content":"select * from t"}}' | .claude/hooks/no-select-star.sh
#   -> a JSON line with "permissionDecision":"deny"

set -uo pipefail

if ! command -v python3 >/dev/null 2>&1; then
  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"no-select-star: python3 not found, so the check could not run. Failing closed on purpose."}}\n'
  exit 0
fi

cat | python3 -c '
import json, re, sys

try:
    event = json.load(sys.stdin)
except Exception:
    print(json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "allow"}}))
    sys.exit(0)

ti = event.get("tool_input", {}) or {}
path = ti.get("file_path", "") or ""

# Only inspect SQL files. Everything else passes.
if not path.endswith(".sql"):
    print(json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "allow"}}))
    sys.exit(0)

# Gather the text this write would put on disk, across Write, Edit, and MultiEdit.
chunks = [ti.get("content", ""), ti.get("new_string", "")]
for e in ti.get("edits", []) or []:
    chunks.append(e.get("new_string", ""))
text = "\n".join(c for c in chunks if c)

# SELECT * (optionally SELECT DISTINCT * or SELECT table.*), case-insensitive,
# any whitespace. count(*) does not match: the * must follow SELECT directly.
if re.search(r"select\s+(distinct\s+)?(\w+\s*\.\s*)?\*", text, re.IGNORECASE):
    reason = ("no-select-star: this query uses SELECT *, which our conventions forbid. "
              "List the columns explicitly, then write it again.")
    print(json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": reason}}))
else:
    print(json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "allow"}}))
'

#!/usr/bin/env bash
# PreToolUse hook: refuse to let Claude Code write to a secrets file.
#
# WHY THIS EXISTS
# "Never touch my .env file" written in CLAUDE.md is a request. The model reads
# it, usually respects it, and one day does not. This script is enforcement: it
# runs on every Write and Edit, before the file is touched, whatever the model
# intended.
#
# INSTALL (two steps, no coding required)
#   1. Save this file as .claude/hooks/protect-secrets.sh in your project, then
#      make it runnable:  chmod +x .claude/hooks/protect-secrets.sh
#   2. Copy the block in settings-snippet.json into .claude/settings.json.
#
# TEST IT WITHOUT CLAUDE (paste this whole line into your terminal)
#   echo '{"tool_name":"Write","tool_input":{"file_path":".env"}}' | .claude/hooks/protect-secrets.sh
#   You should see a JSON line containing "permissionDecision":"deny".
#
# HOW IT DECIDES
# Claude Code hands this script a JSON description of what it is about to do, on
# standard input. The script prints a JSON decision back. "deny" stops the edit
# and sends the reason to the model, which is why the reason is written as an
# instruction rather than an error.

set -uo pipefail

# Add or remove patterns here. One per line, shell glob syntax.
PROTECTED=(
  "*.env"
  ".env"
  ".env.*"
  "*.pem"
  "*.key"
  "*credentials*"
  "*secrets*"
)

# The hook needs python3 only to read one field out of the incoming JSON. If it
# is missing we FAIL CLOSED: a guard that cannot check must not wave things
# through, because a broken guard that returns "allow" is worse than no guard
# at all. You would never know it stopped working.
if ! command -v python3 >/dev/null 2>&1; then
  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"protect-secrets: python3 not found, so the secrets check could not run. Failing closed on purpose. Install python3 or remove this hook deliberately."}}\n'
  exit 0
fi

EVENT=$(cat)
FILE_PATH=$(printf '%s' "$EVENT" | python3 -c '
import json, sys
try:
    event = json.load(sys.stdin)
except Exception:
    print("")
    sys.exit(0)
print(event.get("tool_input", {}).get("file_path", "") or "")
')

# No file path means this event is not a file write we care about. Allow.
if [ -z "$FILE_PATH" ]; then
  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}\n'
  exit 0
fi

BASENAME=$(basename "$FILE_PATH")

# The matched name gets interpolated into the JSON decision below. Escape it
# first, so a path containing a quote or backslash cannot break the JSON and
# turn a deny into a hook error.
json_escape() { printf '%s' "$1" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g'; }
SAFE_BASENAME=$(json_escape "$BASENAME")
SAFE_FILE_PATH=$(json_escape "$FILE_PATH")

for PATTERN in "${PROTECTED[@]}"; do
  # Match the bare filename AND the full path, because Claude may pass either an
  # absolute path, a repo-relative path, or a ./-prefixed path. Checking only one
  # shape is the most common reason a guard like this looks installed and never
  # actually fires.
  # shellcheck disable=SC2254
  case "$BASENAME" in
    $PATTERN)
      printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"protect-secrets: %s is a protected file and must be edited by a human, not by Claude. If this change is genuinely needed, tell the user exactly what to change and let them make the edit themselves."}}\n' "$SAFE_BASENAME"
      exit 0
      ;;
  esac
  # shellcheck disable=SC2254
  case "$FILE_PATH" in
    $PATTERN|*/$PATTERN)
      printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"protect-secrets: %s is a protected file and must be edited by a human, not by Claude. If this change is genuinely needed, tell the user exactly what to change and let them make the edit themselves."}}\n' "$SAFE_FILE_PATH"
      exit 0
      ;;
  esac
done

printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}\n'
exit 0

{
  "_comment": "Paste the hooks block below into .claude/settings.json in your project. If that file does not exist yet, this whole file works as a starting one: delete this _comment line first, since real JSON has no comments. Both hooks run on every Write and Edit.",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/protect-secrets.sh"
          },
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/no-select-star.sh"
          }
        ]
      }
    ]
  }
}

# HANDOFF.md starter

Save this in your project and keep it current during any long piece of work.

**Why this file exists.** A long Claude Code session eventually runs out of room
and compacts itself: it summarises the conversation so far and carries on from
the summary. That happens on a size threshold, not at a sensible stopping point,
so it can land in the middle of something. What practitioners report losing is
the specific stuff: error details, exact file names, the middle steps of a long
piece of debugging, and the reasoning behind decisions already made.

This file is the fix, and it is deliberately low-tech. Anything written here is
on disk, so it survives. Anything living only in the conversation does not.

Write it for a stranger. In practice that stranger is Claude in twenty minutes,
with no memory of the last two hours.

---

## Goal

[What we are trying to achieve, in one or two sentences. Not the task list, the
outcome.]

## Where things stand

[What is genuinely finished. Include one hard fact per item that proves it is
finished, for example a count, a filename, or a check that passed. "Mostly done"
is not a status.]

## What is in flight right now

[The thing being worked on this moment, and how far in.]

## Decisions already made, and why

- **[Decision]**: [why, and what the alternative was]

The "why" is the part that gets lost. Without it, the next session relitigates a
question you already settled.

## Open questions

- **[Question]**: [what would resolve it, and who decides]

## Gotchas already hit, do not rediscover

- [What went wrong, what it looked like, and what fixed it.]

This section is worth more than the rest of the file combined. Every entry is
time somebody already spent.

## Next steps, in order

1. [Next concrete action]
2. [The one after that]

---

## How to use it

- Update it before any long run, and after anything surprising.
- After a reset, a new session, or when answers start feeling vague, say:
  **"Read HANDOFF.md and continue from the next step."**
- If you find yourself re-explaining something you already explained today, that
  belongs in here.