Pragmatic Spec Driven Development — a lightweight framework for AI-assisted software delivery.
Any project containing a pragspec/ directory is explicitly using this methodology.
That directory is the single source of truth for what the system is, how it is built, and why decisions were made — for both humans and AI agents.
Modern AI coding agents work best when they have:
- A clear entry point to load as context before acting
- Dense, single-file units of work they can reason about atomically
- Explicit constraints they must not violate during generation
- Traceable decisions explaining why things are the way they are
Heavy SDD frameworks create cognitive overhead — for humans and agents alike. PragSpec strips it to the minimum that actually powers delivery.
pragspec/
├── spec.md ← Functional Spec + project index. Always read first.
├── architecture/
│ └── overview.md ← Technical Spec: stack, design, constraints
├── features/
│ └── feature-name.md ← One file per feature (functional + technical sections)
├── decisions/
│ └── ADR-001-title.md ← Architecture Decision Records
└── standards/
├── coding.md ← Language/style conventions (enforced)
├── error-model.md ← Error response contract (enforced)
└── api-versioning.md ← Versioning strategy (enforced)
Every agent session follows this read order:
pragspec/spec.md— functional scope, active features, enforced standards listpragspec/architecture/overview.md— tech stack, system design, hard constraintspragspec/standards/*.mdwhereenforced: true— hard constraints for code generation- Target
pragspec/features/feature-name.md— the specific unit of work
This sequence ensures the agent has complete ground truth before touching code.
The project-level functional specification and entry point index.
# Project Name — Spec ## Purpose What the system does and for whom. ## Users Who uses this system and in what context. ## Core Capabilities Numbered list of what the system can do at a high level. ## Non-Functional Requirements Performance, availability, compliance, scale expectations. ## Active Features | Feature | Status | |---|---| | features/feature-name.md | ready | ## Enforced Standards | File | Scope | |---|---| | standards/coding.md | all | | standards/error-model.md | api |
The project-level technical specification.
# Technical Spec ## Tech Stack Language, framework, database, infra — with version pins. ## System Design Key architectural patterns and how components fit together. ## Integration Points External systems, APIs, or services this project depends on. ## Constraints Hard limits: performance SLAs, compliance, platform restrictions.
Every feature file contains both a functional and technical view in one place.
--- status: draft | ready | in-progress | done --- # Feature Name ## Functional ### Why Problem statement and motivation. ### What Behavior, scope, and acceptance criteria. ### Out of Scope Explicit exclusions to prevent scope creep. ## Technical ### Data Model Key entities, fields, and relationships. ### API Contract Endpoints, request/response shapes, error codes. ### Implementation Notes Constraints, patterns, or non-obvious choices the agent must follow. ## Open Questions Unresolved decisions that would block a correct implementation.
Rules:
- No tasks in feature files. Tasks live in your issue tracker (GitHub Issues, Linear, Jira).
- No research dumps. Distill findings into decisions.
- If a decision affects only this feature, note it here. If it affects the system, write an ADR.
Standards files use frontmatter to signal enforceability:
--- enforced: true applies-to: [api, data-model, all] ---
When an agent loads a feature, it must also load all standards where enforced: true and
applies-to matches the feature scope. Standards are hard constraints during code generation,
not optional reading.
Write an ADR when:
- A decision affects more than one feature or constrains future architecture
- A non-obvious tradeoff was made that needs future context
- A direction was actively rejected and you want to prevent re-litigating it
Filename: ADR-NNN-short-title.md
# ADR-NNN: Title ## Status Accepted | Superseded by ADR-NNN | Deprecated ## Context What situation forced this decision. ## Decision What was decided. ## Consequences What this enables and what it constrains.
Scaffold PragSpec in any project:
chmod +x init-pragspec.sh ./init-pragspec.sh [project-name]
See examples/ for complete worked examples.
pragspec/
spec.md ← functional spec + index
architecture/
overview.md ← technical spec
standards/
coding.md
features/ ← empty, grow as needed
decisions/ ← empty, grow as needed
Start here. Add only what earns its place.
| Concern | Heavy SDD (e.g. spec-kit) | PragSpec |
|---|---|---|
| Per-feature docs | 5 files (spec, plan, tasks, research, data-model) | 1 file with Functional + Technical sections |
| Memory / context | Separate constitution.md |
pragspec/spec.md as functional entry point |
| Technical spec | Scattered across templates | pragspec/architecture/overview.md |
| Task tracking | tasks.md per feature |
External issue tracker |
| Templates | Explicit template system | Conventions defined here |
| Standards | Ad hoc | First-class with enforceability frontmatter |
| ADRs | Optional / implicit | Explicit decisions/ folder |
| Project identity | Generic docs/ folder |
pragspec/ — self-describing |