av/facts

什么是 facts？

av/facts 是一种工作流和规范格式，用于将项目管理为 .facts 文件中的原子断言列表。每行是一个简短的结构化陈述，描述应该为真的内容，可选包含shell 命令，由机器运行以验证该断言。

核心目的是让代理和团队保持项目需求可读且可验证：编写粗略事实，精炼为精确规范，然后实现并验证它们。运行 facts check 可查看哪些断言通过、失败或需要手动关注。

主要特性

• 原子“事实”规范格式（.facts）： 每行一个断言，以纯字符串形式编写，按领域使用 Markdown 标题组织。
• 生命周期标签用于进度跟踪： 使用 @draft、@spec 和 @implemented（以及任何自定义标签）显示每个断言在管道中的位置。
• 命令支持的验证： 对于包含 command 的断言，facts check 运行命令，当命令退出码为 0 时认为断言为真。
• 自动化验证和状态分组： facts check 检查文件、运行每个命令，并分组结果（例如，绿色通过、红色失败、黄色手动）；如果有任何失败则非零退出。
• CI 友好的退出码和过滤： 使用标签表达式过滤检查（例如 --tags "mvp and not blocked"），验证规范的子集。
• 代理管理的转换和针对规范的实现： 代理读取事实表，拾取 @spec 断言，构建它们，运行 facts check，并将通过的断言标记为 @implemented，同时规范自我更新。

如何使用 facts

1. 安装 CLI/代理工具（项目提供多种安装选项，包括 Rust 二进制和以下 npx 命令）。
   • 示例：npx skills add av/facts
   • 然后让代理运行 Init facts（例如，“Init facts”），以检测技术栈并创建初始 .facts 文件。
2. 创建或编辑 .facts 文件，使用文档化格式：
   • 添加标题按领域组织（例如 # auth、# data）。
   • 每行添加一个断言。
   • 为每个事实添加生命周期阶段标签，如 @draft、@spec 或 @implemented。
   • 对于可验证断言，包含当断言成立时退出 0 的 command。
3. 运行验证： 使用 facts check 检查和验证所有事实（或使用 --tags 限制检查）。审查哪些通过、失败或需要手动工作。
4. 与代理迭代： 将粗略想法写成 @draft，精炼为 @spec，然后让代理实现 @spec 断言，并在通过 facts check 后标记为 @implemented。

使用场景

• 变更后项目规范验证： 保持活的检查清单，记录必须为真的内容，并在编辑后运行 facts check 快速查看哪些仍成立。
• 将需求转为可执行检查： 将“必须为真”陈述（如同认证行为或数据处理规则）转换为带有命令验证的事实。
• 使用事实生命周期管理进行中的工作： 使用 @draft → @spec → @implemented 沟通进度，确保每个断言要么已实现并验证，要么明确标记需精炼。
• 自动化代码库发现和分类： 使用 facts-discover 技能扫描代码库，按生命周期阶段分类事实，包括添加缺失事实。
• 针对规范实现： 使用 facts-implement 流程，代理读取 @spec 事实，构建代码，用 facts check 验证，并更新标签。

常见问题

facts 只是文档格式，还是真的会验证断言？
两者皆可：无命令的事实可由代理针对代码库验证，而带 command 的则通过运行命令并检查退出码 0 验证。

facts check 做什么？
它检查文件、运行每个提供的命令，按状态（通过/失败/手动）分组结果，如果有任何失败则非零退出。

事实如何组织和跟踪？
事实存于 Markdown/YAML 兼容结构的 .facts 文件中，使用标题组织领域，并用标签（包括 @draft、@spec、@implemented）跟踪生命周期状态。

我能只检查项目的一部分吗？
是的。facts check 支持通过 --tags 和布尔表达式进行标签过滤。

替代方案

• 测试套件（单元/集成测试）： 传统测试可验证行为，但 .facts 检查清单强调人类可读的原子断言和生命周期/状态管道，而非仅自动化通过/失败。
• 静态文档 + 代码审查： 文档可捕获需求，但通常不可直接执行；facts 通过 facts check 将断言与验证绑定。
• 支持需求可追溯性的规范工具： 链接需求与实现的工具可提供可追溯性，但 facts 专用逐行断言格式，支持可选命令执行和基于标签的生命周期转换。