Files
kandev/docs/decisions/2026-08-22-system-oriented-specifications.md
T

83 lines
3.3 KiB
Markdown

# ADR-2026-08-22-system-oriented-specifications: Organize Specifications by System
**Status:** accepted
**Date:** 2026-08-22
**Area:** workflow, infra
## Context
Kandev stores product requirements, technical contracts, and implementation
details in `docs/specs`. Many files now contain all three types of information.
This mixture makes the files difficult to find, maintain, and load into an
agent context.
The repository also uses two directory patterns. Some specifications use a
product group such as `tasks/` or `office/`. Other specifications use one
directory for each feature. The mixed structure weakens ownership and creates
large standalone documents.
## Decision
Keep `docs/specs` as the root for durable product and system specifications.
Organize new specifications by an owning system. Each system can contain these
directories:
- `requirements/` defines required and observable behavior.
- `system-design/` defines the technical design that satisfies requirements.
Use `docs/specs/product/` for Kandev-wide purpose, actors, principles, success
measures, constraints, and the product map. Keep plans and work orders in
`docs/plans`. Keep architecture decisions in `docs/decisions`.
Use stable `REQ-*` identifiers for requirements. Use stable `AC-*` identifiers
for acceptance criteria. System designs and work orders reference these
identifiers. Tests reference acceptance criteria when the mapping is useful.
Use `docs/specs/guide/` as the canonical authoring guide. Skills apply this
guide but do not duplicate its complete rules. A repository linter enforces
the mechanical rules, including file-size limits.
Do not move all legacy specifications in one mechanical change. A migration
must separate product intent from technical design. Each migrated system must
name one new source of truth before legacy content becomes a link or archive.
This decision amends the specification layout in ADR-0001. It does not change
the file-based and progressively loaded knowledge model.
No product specification needs an update. This decision changes the repository
authoring system and not Kandev product behavior.
## Consequences
Requirements and system designs stay close because they share an owning
system. Agents can load one system index and select only the necessary files.
The term `specification` becomes an umbrella term. New documents do not use a
generic `spec.md` filename. Authors must identify each document as a product
document, requirement, system design, ADR, plan, or work order.
The repository needs a controlled migration for existing specifications.
Legacy files remain valid until their owning system migrates. Oversized legacy
files cannot grow beyond their recorded size ceiling.
## Alternatives Considered
### Organize by artifact type
This option used separate top-level trees for requirements and technical
designs. It made artifact types easy to list, but it separated documents that
agents usually read together.
### Put each feature in its own directory
This option put `requirements.md` and `system-design.md` in a feature directory.
It gave strong local grouping, but it recreated the existing standalone-feature
sprawl.
### Use the term blueprint
This option followed an external software-factory model. The term did not match
Kandev terminology and implied a more rigid document than a living system
design.