AgentSkillsCN

mcaf-feature-spec

在 `docs/Features/` 目录下，使用 `docs/templates/Feature-Template.md` 创建或更新功能规格文档：明确业务规则、用户流程、系统行为、Mermaid 图表、验证方案，以及完成定义。在实施复杂功能前，或当系统行为发生变化时，可使用此技能；同时确保规格文档具备可执行性——包含测试流程，并与测试用例保持追溯关联。

SKILL.md
--- frontmatter
name: mcaf-feature-spec
description: "Create or update a feature spec under `docs/Features/` using `docs/templates/Feature-Template.md`: business rules, user flows, system behaviour, Mermaid diagram(s), verification plan, and Definition of Done. Use before implementing a non-trivial feature or when behaviour changes; keep the spec executable (test flows + traceability to tests)."
compatibility: "Requires repository write access; produces Markdown docs with Mermaid diagrams and executable verification steps."

MCAF: Feature Spec

Outputs

  • •docs/Features/<feature>.md (create or update)
  • •Update links from/to ADRs and architecture map when needed

Spec Quality (anti-guesswork checklist)

Write a spec that can be implemented and verified without guessing:

  • •No placeholders: avoid “TBD”, “later”, “etc.”; if something is unknown, list it as an explicit question.
  • •Concrete modules: use real module/boundary names from docs/Architecture/Overview.md.
  • •Rules are testable: numbered business rules with clear inputs → outputs (no vague adjectives).
  • •Flows are executable: scenarios include preconditions, steps, expected results (happy + negative + edge).
  • •Verification is real: commands copied from AGENTS.md, and scenarios mapped to test IDs.
  • •Stakeholders covered: Product / Dev / DevOps / QA each get the information they need to ship safely.

Workflow

  1. •Start from docs/Architecture/Overview.md to pick the affected module(s).
  2. •Create/update the feature doc using docs/templates/Feature-Template.md.
    • •follow AGENTS.md scoping rules (do not scan the whole repo; use the architecture map to stay focused)
    • •keep the feature’s ## Implementation plan (step-by-step) updated while executing
  3. •Define behaviour precisely:
    • •purpose and scope (in/out)
    • •business rules (numbered, testable)
    • •primary flow + edge cases
  4. •Describe system behaviour in terms of entry points, reads/writes, side effects, idempotency, and errors.
  5. •Add a Mermaid diagram for the main flow (modules + interactions; keep it readable).
  6. •Write verification that can be executed:
    • •test environment assumptions
    • •concrete test flows (positive/negative/edge)
    • •mapping to where tests live (or will live)
    • •traceability: rules/flows → test IDs (so tests reflect the spec)
  7. •Keep Definition of Done strict:
    • •behaviour covered by automated tests
    • •static analysis clean
    • •docs updated (feature + ADR + architecture overview if boundaries changed)

Guardrails

  • •If the feature introduces a new dependency/boundary, write an ADR and update docs/Architecture/Overview.md.
  • •Don’t hide decisions inside the feature doc: decisions go to ADRs.