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 plus the root CLAUDE.md memory bank.
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
└── ...
CLAUDE.md # the memory bank: 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.
Memory bank (CLAUDE.md)
The root CLAUDE.md is the always-loaded brief: the stack, key commands, naming conventions, and known gotchas. It is the first thing Claude Code reads.
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.