CLAUDE.md — a generic starting point for any project. The ccc / nnn / gogogo / rrr short codes and the two-issue pattern, safe-git rules, GitHub flow — no stack, no framework, no project tooling. Copy to your repo root and fill in the one Project section at the bottom. Story: workshop-2-demo-oracle.laris.workers.dev/12-short-codes.html

CLAUDE.md

CLAUDE.md — AI Assistant Guidelines

A generic starting point for any project. Nothing here assumes a language, framework, or stack. Copy it to your repo root as CLAUDE.md and add whatever your project needs alongside it.

Distilled from the CLAUDE.md that carried the ccc / nnn / gogogo / rrr short codes across ~20 repos from July 2025 onward, with the project-specific tooling removed.

---

Important Instructions

Command Usage

• NEVER use -f or --force flags with any commands
• Always use safe, non-destructive command options
• If a command requires confirmation, handle it appropriately without forcing

Git Operations

• Never use git push --force or git push -f
• Never use git checkout -f
• Never use git clean -f
• Always use safe git operations that preserve history

File Operations

• Never use rm -rf without explicit user permission
• Always confirm before deleting files
• Use safe file operations that can be reversed

General Guidelines

• Prioritize safety and reversibility in all operations
• Ask for confirmation when performing potentially destructive actions
• Explain the implications of commands before executing them
• Use verbose options to show what commands are doing

---

Short Codes

Four words. Type one and the assistant does the whole routine — no slash, no arguments. They exist because the two expensive things in a long session are losing context and forgetting what you learned.

Code	What it does
ccc	Create a context issue, then compact the conversation
nnn	Plan the next task — runs ccc first if there's no recent context
gogogo	Execute the most recent plan, step by step
rrr	Write a session retrospective

The two-issue pattern

ccc and nnn deliberately write to separate issues:

1. Context issues (ccc) — preserve session state. What happened, what changed, what's pending.
2. Task issues (nnn) — contain the actual plan. What to build, in order.

Keeping them apart is the whole point: a context dump is not a task list, and mixing them makes both harder to read later. nnn checks for a recent context issue and creates one if it's missing, so you can always start from nnn.

---

ccc — Create Context & Compact

When you see ccc, immediately:

1. Run git status --porcelain to get changed files
2. Run git log --oneline -5 for recent history
3. Create an issue with:
   • Current context summary
   • List of changed files
   • Important decisions and changes made
   • Reference to the last PR
   • Current state and pending tasks
4. Forward all context to the issue
5. Continue the conversation with compacted context

Use /compact to compact the conversation after the issue exists.

Example issue format

Title: Context: [Feature/Task Name]

- Current state: [what was completed]
- Last PR: #[number]
- Pending tasks: [what needs to be done]
- Key decisions: [important choices made]
- File changes: [main files modified]

No GitHub on this project? Write the same content to context/YYYY-MM-DD_HH-MM.md instead. The pattern matters, the issue tracker doesn't.

---

nnn — Next Task Planning

Analysis and planning only. No coding.

1. Check for a recent context issue — if none exists, run ccc first
2. Research the codebase for anything the plan depends on
3. Write a task issue containing:
   • The goal, in one sentence
   • Files that will change
   • Step-by-step implementation order
   • How you'll know it worked (tests, a command to run, an observable result)
   • Anything unresolved that needs a human decision

Stop there. nnn produces a plan a different session could pick up cold.

---

gogogo — Execute the Plan

1. Read the most recent task issue
2. Work through its steps in order
3. Verify each step before starting the next
4. Commit as you go, with messages that name what changed and why
5. Open a PR and give the human the link — do not merge it

If a step turns out to be wrong, say so and stop rather than improvising past it. The plan is a hypothesis; contradicting evidence is worth more than finishing on schedule.

---

rrr — Session Retrospective

Create a retrospective containing:

Session header

• Date, start time, duration
• Primary focus of the session
• Current issue number and last PR, for continuity

Content

1. Timeline — what happened, in order
2. AI diary — the assistant's own account of working the session: what it understood, where it went wrong, what surprised it
3. What went well — patterns worth repeating
4. What could improve — where it was slow, wrong, or circular
5. Honest feedback — direct observations on communication, working style, technical decisions, and areas for growth
6. Lessons learned — takeaways for next time

Write with an honest, balanced perspective — not complimentary, but specific and constructive. A retrospective that only says nice things is a wasted file.

File organisation

• Directory: retrospectives/YYYY/MM/
• Filename: YYYY-MM-DD_HH-MM_retrospective.md
• Always include the session metadata header, so sessions chain together

---

Resuming work

1. Check the last context issue
2. Check the last PR: gh pr list --state all --limit 5
3. Read the issue for context
4. Continue from where the previous session stopped

---

GitHub Flow

Always git pull before creating an issue.

1. Create an issue — it's your todo
2. Create a new branch
3. Make the changes
4. Commit them
5. Push to the repository
6. Create a pull request
7. Do not merge it — give the PR link to the human for review

Quick fixes

# 1. Issue, if the human reported a bug
gh issue create --title "Brief description" --body "Details"

# 2. Branch and fix
git checkout main && git pull
git checkout -b fix/descriptive-name
# ... make changes, then run this project's tests

# 3. Commit and push
git add -A && git commit -m "fix: clear description

- What was changed
- Why it was changed"
git push -u origin fix/descriptive-name

# 4. PR — link it, don't merge it
gh pr create --title "Same as commit" --body "Fixes #123"

Conventions

• Branches: feature/description, fix/issue-number, docs/update
• Commits: feat: · fix: · docs: · chore: · refactor: · test:
• PRs: link issues with Closes #123

---

Working Practices

• Test incrementally. Small changes, verified, beat large changes hoped for.
• Read before writing. Open the file; don't infer its contents from its name.
• Environment variables for secrets. Never commit a key, token, or password.
• Say when you're unsure. Flag it before asserting, not after being corrected.
• Report what actually happened. If tests fail, show the output. If a step was skipped, say so.