Spec Harness
Spec Harness is the AI-indexing and memory layer that ships with this boilerplate. It is the difference between an assistant that re-learns your codebase every session and one that already knows your conventions, decisions, and constraints. It lives in the ai_rules/ directory, the .memory/ bank, and the root CLAUDE.md brief that points at both.
Why it exists
LLMs have no persistent memory between sessions and will confidently invent APIs, file paths, and conventions. Spec Harness solves this by giving Claude a curated, version-controlled context layer it reads before writing code — so it follows your rules instead of generic defaults.
The layout
ai_rules/
├── rules/ # enforceable coding rules (the "operating system")
│ ├── nextjs.md
│ ├── seo.md
│ ├── design_rule.md
│ ├── performance-budget.md
│ ├── best-practices.md
│ ├── core.md
│ └── context_management.md
├── generators/ # repeatable scaffolds (pages, sections, features)
├── decision_records/ # ADRs — why a choice was made, so it isn't relitigated
├── context_map.md # high-level map of the codebase for fast orientation
├── app_approach/
│ └── app-context.md # what YOUR product is, written by pnpm run init
└── ...
.memory/ # the memory bank: brief, product, system, active, progress
CLAUDE.md # the always-loaded brief: stack, commands, conventions, gotchasThe pieces
Rules (ai_rules/rules/)
Enforceable, domain-specific instructions: Next.js patterns, SEO requirements, design tokens, performance budgets. Claude reads these before touching the relevant area. See Best practices for the condensed version.
Generators (ai_rules/generators/)
Repeatable scaffolds for common tasks (a new page, a marketing section, a feature). They keep new code consistent with what already exists instead of reinventing structure each time.
Decision records (ai_rules/decision_records/)
Architecture Decision Records (ADRs) capture why a choice was made — e.g. how the hero is split into server and client components. They stop the AI (and your team) from undoing intentional decisions.
Context map (ai_rules/context_map.md)
A high-level index of the codebase so Claude can orient quickly: where components live, how data flows, which file owns what.
App context (ai_rules/app_approach/app-context.md)
The short, honest description of your product: what it is, who it serves, the primary goal, the voice, and what an agent must never claim. It is the file an agent reads before it writes product code or a blog post. pnpm run init writes it from seven questions.
Brief and memory bank (CLAUDE.md + .memory/)
The root CLAUDE.md is the always-loaded brief: the stack, key commands, naming conventions, known gotchas, and the order to read everything else in. It is the first thing Claude Code reads. .memory/ is the per-project bank the memory-bank step fills, so a session starts with your product loaded rather than the boilerplate.
How to use it
CLAUDE.md and the relevant files in ai_rules/. Before any code change, the rules ask Claude to run the anti-hallucination checklist in ai_rules/rules/context_management.md.When you rebrand the boilerplate, sweep ai_rules/ and CLAUDE.md for project-specific references and replace them with your own product details. Keep the structure — it is what makes the system durable across sessions.
app-context.md ships as a placeholder. CLAUDE.md instructs the agent to say so while it still is, and then either run pnpm run init for you or ask you those same seven questions. What it must not do is infer your product from the boilerplate's own marketing copy, which describes AI Web Launcher rather than the thing you are building with it.