跳到主要内容

内置元数据

HarnSpec Spec 在 frontmatter 中存储一小组系统管理的字段，以便人类、仪表板和 AI 代理共享同一事实。保持这些字段准确——自动化、看板、Agent Skills 驱动的工作流都依赖于它们。

状态生命周期​

  1. planned — 意图已捕获，实现尚未开始。
  2. in-progress — 工作正在积极进行中。
  3. blocked — 外部依赖阻止进展。
  4. complete — 实现完成并验证。
  5. archived — 仅供历史参考。

在实现开始或停止时立即更新状态；状态跟踪工作，而非 Spec 编写过程。使用 harnspec update <spec> --status <value> 以便每个工具（和 AI 代理）看到相同的状态。

关系​

HarnSpec 使用 depends_on 来捕获阻塞性依赖：

  • depends_on — 方向性依赖。Spec A 在 Spec B 完成之前无法开始。 
    depends_on:
      - 082
    在 harnspec deps 中显示为 →，并自动在依赖项上添加"Required By"条目。

仅当工作确实必须按特定顺序完成时才使用 depends_on。对于共享上下文但不互相阻塞的松散相关 Spec，请在 Spec 内容中记录关系，而不是使用元数据。

优先级和标签​

这些字段使 Spec 可过滤并保持计划轻量级。

  • priority 传达紧急性或影响。典型值：low、medium、high、critical。
  • tags 提供跨组合的快速切片。坚持共享词汇表（例如 frontend、backend、docs、infra）。 
    priority: high
    tags: [api, backend, security]

每个 Spec 目标 2-4 个标签。太多标签会降低信号并使搜索产生噪音。

示例 Frontmatter​

---
status: in-progress
priority: high
tags: [api, backend]
depends_on: [082]
created: '2025-11-16'
---

为什么元数据Spec很重要​

  • 项目保持诚实 — 看板、燃尽图和路线图导出直接使用这些字段。
  • AI 保持一致 — 代理根据 status、priority 和依赖关系决定是编辑 Spec 还是开始实现。
  • 上下文共享改进 — 标签、关系和状态转换告诉新来者在哪里插入，无需另一次会议。

将 frontmatter 视为代码：一旦现实发生变化就更新它，并在合并前使用 harnspec validate 验证。