Project Name:
Version:
Status:
Last Updated:
This document is the authoritative, canonical source of truth for this project. All architectural, behavioral, and implementation decisions are governed by this specification. Sections may be left empty during early drafting, but headings and structure must remain intact.
Describe exactly what this document governs and what it explicitly does not govern.
Define how changes to this document are made, versioned, reviewed, and approved. Specify what constitutes a breaking change.
Identify who this document is written for (e.g., AI coding agents, maintainers, future contributors with no prior context).
Clearly and precisely describe the problem being solved. Avoid marketing language.
Summarize what the project is, what it does, and what it deliberately does not do.
Define concrete, testable conditions under which the project is considered successful.
List features, behaviors, and responsibilities that are explicitly supported.
List features or behaviors that are explicitly excluded, even if they seem adjacent or implied.
Describe architectural, philosophical, or functional directions intentionally avoided.
Document assumptions about operating systems, hardware, network conditions, and runtime environments.
Specify language choices, dependency limitations, compatibility requirements, and other hard constraints.
Describe expectations placed on operators, maintainers, and users.
Describe the system as a set of major components and their relationships.
For each major component, describe its responsibilities, inputs, outputs, and failure modes.
Explain startup behavior, shutdown behavior, and runtime execution characteristics.
Define what data exists, who owns it, and where it resides.
Specify file formats, schemas, serialization rules, and field-level expectations.
Describe how system state changes over time, including lifecycle and cleanup rules.
Define all user-facing interfaces such as CLI, GUI, configuration files, or dashboards.
Describe APIs, IPC mechanisms, plugin systems, and versioning expectations.
List external systems, services, or dependencies and how integration is handled.
Describe how the system approaches errors (fail-fast vs fail-soft, silent vs noisy).
Define categories of errors and how each is handled.
Specify logging requirements, destinations, and redaction rules.
Describe what threats are considered and which are explicitly out of scope.
Define expectations around secrets, encryption, access control, and data handling.
Describe foreseeable misuse scenarios and defensive design decisions.
Document assumptions about scale, concurrency, and data volume.
Define latency, throughput, and resource usage targets.
Explain how the system behaves when limits are exceeded.
Describe build tooling, determinism expectations, and reproducibility requirements.
List produced artifacts, naming conventions, and versioning rules.
Explain how the project is distributed, updated, and rolled back.
Describe unit, integration, end-to-end, and manual testing approaches.
Define how test data is sourced, generated, and maintained.
Specify conditions required for work to be considered complete.
List required documentation artifacts and their scope.
Define when documentation must be updated relative to code changes.
Describe the types of changes permitted during maintenance.
Define how breaking changes are introduced and communicated.
Specify conditions under which the project is deprecated or retired.
List unresolved decisions or questions. Each entry must be explicit and bounded.
Note: All sections are required for structural consistency. Sections may remain intentionally empty during early stages, but headings must not be removed or renamed.