Requirements Tracking (Spec Coding)

Workflow

1. Discover conventions
   • Read the repository's

     AGENTS.md

     , requirements index, and existing document structure, and follow existing numbering and paths.
   • When no conventions exist, use

     docs/project.md

     and requirement(R-xx).
   • Before registration, search the index by module, interface, configuration, or business rule, and read requirements and acceptance criteria whose scope intersects.
2. Register
   • Register the requirement in the index; by default, use a single requirement MD.
   • When refining or correcting the same requirement, prefer updating its original ID; create a new ID and record the relationship only for an independent requirement.
   • Refer to spec-template.md and spec-example.md.
3. Finalize
   • Clearly document the scope, non-goals, acceptance criteria, key decisions, and open questions.
   • Once open questions affecting implementation are resolved, transition the status to

     开发中

     , and then modify the code.
4. Verification first
   • For each acceptance criterion, select the lowest-cost verification level sufficient to demonstrate the behavior.
   • First establish a failing baseline or document the existing gap, then implement until it passes.
   • One acceptance criterion may be proven by multiple test cases, and one test case may cover multiple related criteria.
5. Implementation and convergence
   • Implement according to the verification mapping; when complete, update the corresponding verification items and replace stale conclusions.
   • If it passes in the test environment but has not yet been released, keep the status as

     待回归

     .
   • After the actual release, transition the status to

     已上线

     .
6. Wrap-up
   • Update the index when the entry point, affected scope, related requirements, or status changes.
   • When superseding existing rules, mark the old entry's replacement relationship and applicable scope to avoid having two sets of rules valid at the same time.
   • Update

     AGENTS.md

     when long-term repository rules or authoritative entry points change.
   • Check the rules, references, and verification scope against the current diff to avoid leaving stale conclusions or duplicate records.
   • Reference the spec path or ID in the commit message.

Document Organization

docs/xxx需求.md

• Index: Maintain the entry point, status, affected scope, and related requirements; do not duplicate the body text, test counts, or commands.
• Interface documentation: Intended for consumers and may independently maintain external contracts.
• Splitting criteria: Split only when explicitly requested by the user or when a particular section genuinely needs independent maintenance; do not split based on length or the number of iterations.
• Existing structure: Follow repository conventions and do not force directory migrations; after splitting, use links for references and do not duplicate records.

Continuous Iteration and Review

• Focused review: In each iteration, explain behavior changes, impact scope, and unverified items; for small changes, show only the local diff.
• Converge in place: Update the corresponding rules and acceptance criteria, remove stale descriptions, and do not append sections by conversation turn.
• Sync as needed: Update documentation according to the actual impact; do not create additional change files or add confirmation steps.
• Formatting isolation: Separate requirement changes from formatting-only cleanup to avoid reformatting unrelated content.

Core Spec Requirements

• Status:

  规划中 / 开发中 / 待回归 / 已上线

  . The core spec maintains the status, while the index displays only a summary.
• Scope and relationships
  • Clearly define the current scope and non-goals; when scopes overlap, distinguish duplication, dependency, extension, supersession, and conflict.
  • Explain the specific relationship in this document and link related requirements. A supersession must identify the acceptance criterion or rule and its effective scope.
  • Sharing a module does not imply a conflict, and numbering order does not indicate supersession; unverified relationships must not be stated as definitive conclusions.
• Acceptance criteria
  • Describe testable behavior. Chinese conditional sentences should use 「当、应、若、则」.
  • 「应」 denotes a requirement that must be met; state simple rules directly without forcing them into a complete conditional sentence.
  • Write IDs as requirement(R-01) and acceptance criterion(AC-1), and write ranges as acceptance criterion(AC-1~AC-4).
  • Use half-width characters for parentheses and range connectors, with no spaces on either side; preserve existing IDs and paths.
• Input constraints: Specify the format, count/length limits, null values, and behavior when limits are exceeded.
• Key design: Record conclusions and rationale that affect implementation or acceptance in this document as needed.
• Open questions and assumptions
  • Distinguish blockers, default values, and assumptions to verify, and explain the basis and verification method; list unresolved rule conflicts here as well.
  • Do not implement dependent content until the blocker is resolved; authorized work that does not depend on it may continue.
  • List integration verification gaps separately for visual effects or upstream semantics that unit tests cannot prove.
• Verification mapping
  • Map acceptance criteria, risks/behavior, verification levels, and test cases/evidence; do not require every criterion to map to a unit test.
  • When standalone verification files already exist, keep only the coverage relationships and links in the spec, and do not duplicate execution results.
• Verification results
  • By default, centralize results in this document's verification section, recording the current conclusion, scope, version or change basis, and evidence.
  • Update existing entries rather than appending a summary after each iteration; remove stale conclusions and leave history to Git.
  • Partial verification proves only the corresponding scope. Mark other changes as unverified, and do not carry forward an old version's conclusion that all checks passed.

Boundaries with the Testing Skill

• Skill available: Use

  spring-testing

  to select the testing level and implementation approach.
• Skill unavailable: Follow the repository's existing testing conventions.

Chinese Markdown

Constraints

• Create documentation based on risk: Whether to create a new spec depends on the risk, collaboration, and regression surface, rather than the number of changed lines.
• Update rules first: For requirement changes, update the core spec and corresponding verification mapping before modifying the code.
• Cross-repository synchronization: Record the requirement landing points, propagation scope, and synchronization status in the core spec.
• Environment guidance: Put build and deployment steps in the runbook; retain necessary constraints, entry points, and links in

  AGENTS.md

  .
• Entry-point conventions: Do not require creating or copying compatibility files; follow the repository's single-source strategy in

  AGENTS.md

  /

  CLAUDE.md

  .