Guardrails Writer - Engineering Specification Writing

Core Positioning

• Guardrails = Global consistency constraints, not PRD/HLD/LLD.
• Emphasize Must/Should/Nice and verifiability, rather than implementation details.
• Risk first: Prioritize covering high-cost risks such as security, data, interfaces, release, stability, etc.

When to write/update (equally important)

• New project/new repository/new platform launch
• Significant changes in tech stack or architecture (framework, cloud platform, database, runtime)
• Expansion of multi-team collaboration or cross-system collaboration
• Consistency issues (quality/security/stability) found during incident review
• New compliance requirements/security audit requirements
• API/data contracts evolve from internal use within a single team to external/cross-team use

• Similar issues occur repeatedly during LLD reviews
• Changes in release/rollback processes
• Introduction of key third-party services or infrastructure

• Only for special implementation of a single function
• Only for one-off temporary policies

What to write / What not to write (equally important)

Should be included

• Consistency rules across modules/teams
• Mandatory security, interface, data, release and observability standards
• Allowed scope and default options (e.g. list of available frameworks/libraries)
• Verification methods (lint/CI/review)
• Exception processes (who approves, validity period, how to record)

Should not be included

• Function-level UI details, page copy, pixel-level design
• Specific algorithms/functions/classes/configuration parameters
• Specific database fields or DDL
• Process design for a single function

Workflow

Phase 0: Context collection

1. Use Glob to scan existing specifications, ADR, architecture descriptions, CI rules, historical incident records
2. AskUserQuestion to confirm scope, tech stack, existing specifications (see

   references/askuser-templates.md

   for template)

Phase 1: Determine scope and maturity level

• Clarify applicable systems/teams/boundaries
• Select maturity level (v0 baseline / v1 standard / v2 enhanced)
• Mark the reason for this update and effective time

Phase 2: Output rules by domain

• Use template

  references/guardrails-template.md

• Each rule must include: Rule ID, Level, Rule, Rationale, Verification, Owner
• Must include LLD module requirements (Required/Optional/Forbidden)

Phase 3: Conflict and reuse check

• No conflict with existing specifications
• Clearly state reused existing standards/tools (reference path)
• Mark exceptions and expiration time

Phase 4: Self-check

• Use

  references/guardrails-checklist.md

  to self-check integrity and enforceability

Output requirements

• Meta information (version, Owner, status, effective time, review cycle)
• Applicable scope and non-applicable scope
• Rule classification and verification methods
• LLD module requirement table
• Guardrails for each domain (frontend, API, backend, data, security, operation and maintenance, release, etc.)
• Exception process and change record

Interaction specifications

• When scope/tech stack/existing specifications are needed, you must AskUserQuestion
• Do not guess when evidence is insufficient, ask the user to provide basis

Reference documents

references/guardrails-template.md

references/guardrails-checklist.md

references/askuser-templates.md