Part VIII: Repository Architecture and Reusable Intelligence
How to Structure Projects for SDD and Build Intelligence That Compounds Over Time
Spec-Driven Development is not just a methodology—it is an architecture. The way you organize your repository, separate intent from implementation, and capture recurring patterns determines whether SDD scales or collapses under its own weight. Part VIII addresses the structural foundations that make SDD sustainable: repository architecture, reusable intelligence, and advanced context engineering.
This part answers three critical questions:
- Where does everything go? — How to structure a repository so that specifications, agents, rules, and code coexist without chaos
- How do we avoid reinventing the wheel? — How to extract and reuse intelligence so that every project accelerates the next
- How do we manage context at scale? — How to load the right information at the right time when projects grow large
What You Will Learn
Chapter 23: Repository Architecture for SDD
You will learn the canonical SDD repository structure: specs/ (specifications as source of truth), agents/ (AGENTS.md, skills, subagents), .cursor/rules/ (editor configuration), src/ (implementation), tests/ (test suites), and memory/ (constitution, ADRs, context files). You will understand why separating intent (specs/) from implementation (src/) matters, how to organize global specs, feature specs, and constraint documents, and how the memory/ directory captures project identity. A hands-on tutorial walks you through setting up a complete SDD repository from scratch. You will also learn feature branch workflows (specs/[branch-name]/), version controlling specifications alongside code, monorepo considerations, and how to migrate an existing project to SDD structure.
Chapter 24: Reusable Intelligence Patterns
You will learn what Reusable Intelligence (RI) is and why every SDD project produces two outputs: the product code and the reusable intelligence. You will explore the types of RI: skills (SKILL.md) for 2–4 decisions with human guidance, subagents for 5+ autonomous decisions, Architectural Decision Records (ADRs), Prompt History Records (PHRs), and intelligence templates. You will master the P+Q+P pattern for designing intelligence: Persona (who the agent is), Questions (what to ask before acting), Principles (rules for execution). You will distinguish horizontal intelligence (patterns across projects: testing, security, API design) from vertical intelligence (domain-specific: fintech, healthcare, e-commerce). A tutorial guides you through extracting reusable intelligence from a completed feature: identifying patterns, creating a skill, writing an ADR, and saving a PHR. You will understand the intelligence maturity model: ad-hoc → documented → templated → automated.
Chapter 25: Advanced Context Engineering
Building on Chapter 8 fundamentals, you will learn context architecture for large projects: layered context (constitution → domain → feature → task), context inheritance (how rules cascade), and context composition (combining multiple sources). You will understand memory systems: short-term (conversation), medium-term (checkpoint documents), and long-term (constitutions, ADRs, skills). You will apply the context quality formula: Relevance × Precision × Freshness. You will implement automated context loading: file-scoped rules on glob patterns, intelligent activation from task analysis, and on-demand skills. You will learn context debugging when AI produces unexpected results, token optimization (summarization, progressive detail loading, context pruning), and multi-agent context sharing. A tutorial walks you through designing a context architecture for a running project: defining layers, creating loading rules, and testing context quality with implementation tasks.
The Connection
The three chapters form a structural progression:
- Chapter 22 establishes where things live—the repository layout that makes SDD navigable and maintainable.
- Chapter 23 establishes what to capture—the reusable intelligence that compounds across projects.
- Chapter 24 establishes how to load—the context engineering that ensures the right information reaches the right agent at the right time.
Together, they transform SDD from a workflow into a system: a repository that scales, intelligence that accelerates, and context that stays relevant.