Skip to content

Glossary

The big picture: Blueprint borrows words from three worlds — AI agents, Git, and CI — and uses them precisely. This page defines each one in a sentence or two.

Why it matters: Most confusion in these docs comes from one undefined word. If a page loses you, the term is probably here.

Claude Code — Anthropic’s command-line coding assistant. You run claude in a project folder, describe what you want, and it reads files, runs commands, and edits code. Blueprint is a set of instructions and tools that shape how it works.

Session — one running Claude Code conversation. It remembers what it read and did until you /clear it or close it.

Context — everything a session currently “has in mind”: your messages, the files it read, command output. Context costs money every turn and degrades when it gets very long, which is why the docs keep telling you to keep it small.

CLAUDE.md — a Markdown file Claude Code reads automatically (the root one at the start of every session; nested and paths:-scoped ones when Claude works with matching files). It is how you tell the assistant your project’s rules once, instead of repeating them in every prompt. Blueprint ships four kinds:

  • the root CLAUDE.md — this project’s Claude Code workflow, held to 200 lines by check-claudemd-size.sh; its first line imports AGENTS.md, the agent-agnostic project contract; the reference material behind them is in docs/harness/;
  • nested ones such as scripts/CLAUDE.md — loaded only when Claude works on files in that folder;
  • .claude/rules/*.md — topic files; a paths: glob in the frontmatter loads one only when Claude works with a matching file;
  • global-claude-md.example — an optional template for personal preferences you may copy to ~/.claude/CLAUDE.md. Project rules do not go there.

Agent (subagent) — a separate Claude instance that the main session starts to do one focused job, such as “review this diff for security problems.” It gets a fresh, empty context, does the job, and reports back. Blueprint’s agents live in .claude/agents/, one Markdown file each. See Agents.

Skill (slash command) — a packaged, multi-step workflow you start by typing /name, such as /mr to open a merge request. Skills live in .claude/skills/. See Skills.

User-invoked only — a skill marked disable-model-invocation: true. Claude can’t start it on its own; only you can, by typing it. Blueprint uses this for anything that touches the outside world or spends real money (/mr, /release, /wave). The docs mark these with ⛔.

Hook — a small script Claude Code runs automatically at a set moment, such as just before it edits a file. Hooks are deterministic: they run every time, whether or not the model remembers to. Blueprint’s live in .claude/hooks/.

Model tiers (Opus, Sonnet) — Claude comes in sizes. Opus is the stronger, pricier reasoner; Sonnet is faster and cheaper. Blueprint gives judgment-heavy work (architecture, security, design) to Opus and checklist work (scans, test scaffolds) to Sonnet. Each agent’s file names its tier in its model: line.

Fan-out — one agent starting several more. Useful for parallel scanning, expensive when it runs away. Blueprint caps it — see Fan-out ceiling.

Persona — a written profile of one kind of user (their goal, their frustration). The /voc skill role-plays your personas to stress-test a feature idea. It’s a design aid, not user research.

Harness — the set of files around Claude Code that steer it: rules (CLAUDE.md, AGENTS.md), agents, skills, hooks, and the gates that check its work. Blueprint is a harness, not an application.

VoC (Voice of the Customer) — the /voc skill: a simulated panel of your personas that reviews a feature idea before design starts. It is modeled feedback, not user research.

Wave — the /wave skill, the Build step: it runs one or more issues in parallel, one agent and one worktree per issue, up to a cap, and audits each branch with completeness-check before its MR. See Start work with /wave.

Memory — notes Claude Code saves between sessions in ~/.claude/projects/…/memory/. Useful for lessons learned; /memory-audit keeps it tidy.

Repository (repo) — the project folder and its full change history.

Tracker — the project’s issues, their comments, and the MRs that close them. In Blueprint’s rule, decisions and progress live here and reviewed artifacts live in the repo; see Where things live.

Branch — a named line of work. Every change in Blueprint happens on its own branch, never directly on main.

Commit — one saved snapshot of changes, with a message. Blueprint uses conventional commits (feat:, fix:, …).

Merge request (MR) — GitLab’s request to merge a branch into main, with a description, a review, and a pipeline. GitHub calls this a pull request (PR).

Issue — a tracked unit of work in GitLab. In Blueprint every change starts from one. See Issues are the unit of work.

Milestone — a group of issues with a target date, usually one release.

Worktree — a second (or third…) checkout of the same repo in its own folder, on its own branch. Blueprint’s scripts/wt makes one per issue so parallel sessions never trip over each other. See Parallel work.

glab / gh — the GitLab and GitHub command-line tools. Blueprint’s scripts use whichever matches your origin remote.

CI pipeline — the set of automated jobs GitLab runs on every MR (and on main and on tags). A green pipeline means every blocking job passed.

Gate — any check that can say no: a CI job, a pre-push script, or a review agent. Blueprint’s rule is that a gate’s green must be evidence, so every gate script can prove it still fails when it should. See Harness gates.

Self-test — a gate’s --self-test mode: it builds a deliberately broken example and confirms the gate rejects it.

Git hook — a script Git runs on your machine at git commit (pre-commit) or git push (pre-push). Not the same thing as a Claude Code hook.

Pre-MR gate batch — the four review agents (regression-check, security-review, rbac-check, perf-check) that read the same diff, run together in parallel before an MR opens.

Gate ledger — the ## Gates section of every MR description: one line per gate, saying how many findings it produced. It’s how you learn which gates earn their keep.

Fast path — the row of the Fast paths by change class table in CLAUDE.md that matches a change, which lists exactly which gates it needs. A typo fix doesn’t get an architecture review.

Changelog fragment — a one-line file in changelog.d/ describing one change. Release time stitches them into CHANGELOG.md.

Fail closed — when a check can’t get an answer (network down, service unreachable), it reports failure rather than quietly passing.