Backend Guidelines (reference)

The full file inventory for a backend module's overview/ guidelines — what the backend architect produces, who reads each file, and how the files come into being. For the overview, the override levers, and the content principles, see Project Guidelines.

Backend guidelines live per module at:

.swifter/specs/{module}/overview/

They are produced by swifter-backend-architect:create-guidelines — a thin command that invokes the update-architecture-guidelines skill, which is the real 10-step orchestrator. (The database architect, swifter-database-architect, has a parallel create-guidelines of the same shape.)

The 16-file set

create-guidelines produces 16 files: 8 core + CODING_GUIDELINES.md + 7 NFR files. The set is read by backend analyst, backend developer, and tester.

Every file shares a single hard limit of 200 lines (the SWFT copyright header on line 1 counts toward the budget). There is no per-file budget variation — the cap is uniform and is paired with dense-formatting rules (tables over prose, no blank rows, omit empty sections).

File	What it pins	Read by	Hand-edit
STACK.md	Technology stack	Analyst · Developer · Tester	Easy
STRUCTURE.md	Directory layout	Analyst · Developer · Tester	Easy
ARCHITECTURE.md	Architecture layers	Analyst · Developer · Tester	Easy
CONVENTIONS.md	Naming, code conventions	Analyst · Developer · Tester	Easy
TESTING.md	Testing strategy	Analyst · Developer · Tester	Easy
INTEGRATIONS.md	Integration patterns	Analyst · Developer · Tester	Easy
CONCERNS.md	Cross-cutting concerns	Analyst · Developer · Tester	Easy
PITFALLS.md	Known pitfalls	Analyst · Developer	Easy
CODING_GUIDELINES.md	8-row capstone of binding coding rules, synthesised from the 8 core + 7 NFR files	Analyst · Developer	Derived — shape its inputs + the gate
nfr/NFR_PERFORMANCE.md	Timeouts, retry, cache	Analyst · Developer	Gate — NFR-scope step
nfr/NFR_SCALABILITY.md	Scaling, pooling, rate limiting	Analyst · Developer	Gate — NFR-scope step
nfr/NFR_SECURITY.md	Auth, authorization, PII	Analyst · Developer	Gate — NFR-scope step
nfr/NFR_AVAILABILITY_RELIABILITY.md	Health probes, circuit breakers	Analyst · Developer	Gate — NFR-scope step
nfr/NFR_USABILITY_ACCESSIBILITY.md	WCAG, i18n / l10n	Analyst · Developer	Gate — NFR-scope step
nfr/NFR_MAINTAINABILITY.md	Observability, error format	Analyst · Developer	Gate — NFR-scope step
nfr/NFR_AUDITABILITY_LOGGING.md	Audit trail, structured logging	Analyst · Developer	Gate — NFR-scope step

Which skill writes what

Skill	Writes
generate-foundational-guidelines	STACK.md, STRUCTURE.md
generate-core-guidelines	ARCHITECTURE.md, CONVENTIONS.md, TESTING.md, INTEGRATIONS.md, CONCERNS.md, PITFALLS.md
generate-nfr-guidelines	the 7 nfr/NFR_*.md files
generate-coding-guidelines	CODING_GUIDELINES.md (the 8-row capstone)

The 6-topic confirmation gate

Before generating on an amendment round, the orchestrator drives a blocking 6-topic confirmation gate:

1. architecture (approach)
2. locations (codebase locations)
3. suggestions
4. pitfalls (pitfall mitigations)
5. nfr (NFR scope)
6. principles (mandatory principles)

This is the primary place the team shapes backend content. On a fresh first run (no prior artifacts) the gate is skipped — there's nothing to refine yet.

Regeneration model

update-architecture-guidelines distinguishes three startup states:

• Fresh round 1 (no archives) — generate all 16 from a codebase scan; no scope gate.
• Mid-round resume (status: in_progress) — resume at the live current_step.
• Amendment round (round archives present) — run the scope gate first, then refresh.

On every round the architect scans the codebase and the existing overview files and re-runs the generate-skills. There is no per-file "preserved vs overwritten" distinction — all 16 are (re)produced, with existing content fed back in as input. Practical consequences:

• CODING_GUIDELINES.md is derived from the 8 core + 7 NFR docs — hand-edits are re-synthesised away. Edit its inputs instead.
• NFR content is shaped through the NFR-scope gate step, not by hand-editing nfr/*.md.
• Per-layer rule files at overview/coding-rules/{folder}.{artifact_type}.md are authored by the developer plugin (generate-coding-rules), not the architect. The architect's final step only edits them in place to eliminate drift and never creates new ones.
• No module-type guard. Nothing validates the target module type before generating — create-guidelines will produce the 16-file set against whatever module it's pointed at, so run it on the module whose backend guidelines you actually want.

Reader matrix

File(s)	Backend analyst	Backend developer	Tester
STACK, STRUCTURE, ARCHITECTURE, CONVENTIONS, TESTING, INTEGRATIONS, CONCERNS	✅	✅	✅
PITFALLS	✅	✅	❌
CODING_GUIDELINES	✅	✅	❌
7 × NFR	✅	✅	❌

• The backend analyst reads every file in overview/ and overview/nfr/ (globs and reads all, no pre-filter).
• The backend developer reads the core files it names plus all 7 NFR files when present.
• The tester reads 7 of the 8 core (everything except PITFALLS) and none of the NFRs or CODING_GUIDELINES — see Tester Guidelines.