Build Protocol · Engineering

Software engineering isn't writing a long document — it's building a system that runs correctly in production. This skill enforces the discipline to get there without late-night rollbacks.

When to Use

Triggers (any one):

• Building a multi-module system (3+ services / modules)
• Producing D1-DN design documents before implementation
• Deploying to production (runbook required)
• Any PR merge that changes DB schema, API surface, or auth paths
• Explicit requests: "build service", "做系统", "write design doc", "deploy plan", "API spec"

Don't use for:

• Pure knowledge-base / textbook production (use build-protocol)
• One-off scripts < 100 lines with no deployment
• Read-only analysis with no code output

Inherits from build-protocol

All 8 iron rules apply unchanged:

Engineering-Specific Iron Rules

The 12-Step Engineering Workflow

1.  Requirements      → Scope, non-goals, constraints
2.  Design Doc D1     → System architecture + data flow
3.  Design Doc D2-DN  → Per-subsystem: API surface, DB schema, auth
4.  Schema Design     → DB migrations, index plan, partition strategy
5.  API Contract      → Exact request/response shapes (OpenAPI or equivalent)
6.  Plan              → Break into tasks, assign owners, identify critical path
7.  Prepare           → Sub-agent specs (≤3000 chars/task, self-contained)
8.  Execute           → Code + unit tests (≤2 parallel sub-agents)
9.  Review            → PR review by a different agent/context
10. Audit             → Security / performance / 3-layer consistency ⚠️ UNMISSABLE
11. Deploy Runbook    → Step-by-step prod deploy with verification checkpoints
12. Rollback Plan     → Canary + rollback trigger conditions + recovery steps

See references/engineering-workflow.md for detailed per-step checklists.

Design Doc Series Standard

Every D[N] must contain — no exceptions:

See references/design-doc-checklist.md for the full machine-checkable checklist.

Machine-Verified Consistency Checks

Before Step 10 (Audit), run references/audit-script-engineering.sh:

• Env var consistency: .env.example ↔ config/*.ts ↔ docker-compose.yml ↔ k8s ConfigMap
• DB column naming: init.sql definitions ↔ query layer ↔ TypeScript interfaces
• API path: backend route definitions ↔ frontend fetch calls ↔ design doc spec
• Import paths: no broken references in the codebase
• Secrets not in code: scan for AKIA, sk-, ghp_, hardcoded passwords
• TODO markers: all TODO/FIXME in src/ must be tracked issues, not forgotten

🔴 failures block deploy. Not suggestions — blockers.

Rollback / Hotfix Protocol

Canary rules: Route ≤10% traffic to new version first. Wait ≥15 minutes. Check error rate. Proceed or rollback — not both.

Anti-Patterns

Gotchas

• PG partition tables: ALTER TABLE ... ADD COLUMN must target the parent table, not a partition
• FK migration order: child tables' FKs must reference tables created in earlier migrations — order matters
• Env var naming drift: DB_HOST in .env.example, process.env.DATABASE_HOST in code = silent undefined at boot
• SigV4 URL encoding: + encodes to %2B in path but + (space) in query string — wrong encoder = auth failure
• import vs require in mixed TS/JS: .js extension required in ESM import even when source is .ts
• Canary traffic split with sticky sessions: if users are session-pinned, 10% split becomes 0% or 100% per user

References

• references/engineering-workflow.md — 12-step workflow with per-step checklists
• references/design-doc-checklist.md — Machine-checkable D[N] sections
• references/audit-script-engineering.sh — Bash template for consistency checks

Related Skills

• build-protocol — Parent skill for knowledge/textbook production
• engineering-discipline — Coding standards and PR hygiene

Created: 2026-04-30 · Derived from: build-protocol v1.1 Validated against: multi-service system post-mortems (schema drift, FK order, env var naming, SigV4 trap)