Back to Details

facts

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

facts

facts

A CLI for fact-driven development. You use it to specify what must be true about a project, then validate that reality matches.
Project: https://github.com/av/facts
一款面向事实驱动开发的CLI工具。你可以用它定义项目必须满足的事实，然后验证实际情况是否符合这些定义。
项目地址：https://github.com/av/facts

Installing

安装

If 
facts
is not installed, install it with one of:
bash
curl -fsSL https://raw.githubusercontent.com/av/facts/main/install.sh | sh
bash
npm install -g @aspect-build/facts
bash
pip install facts-cli
Verify with 
facts --version
.
如果尚未安装
facts
，可以通过以下任一方式安装：
bash
curl -fsSL https://raw.githubusercontent.com/av/facts/main/install.sh | sh
bash
npm install -g @aspect-build/facts
bash
pip install facts-cli
通过
facts --version
验证安装是否成功。

Core idea

核心理念

A 
.facts
file is a flat list of atomic truth statements about a project. Each fact can optionally have a shell command that verifies it. The fact sheet serves as both specification (what should be true) and documentation (what is true) — the difference is just which direction you're working from.
- the API returns JSON
- label: project builds
  command: cargo build
- label: tests pass
  command: cargo test
  tags: [ci, core]
That's the entire format. Plain strings for simple facts, mappings when you need a command, tags, or explicit ID. Allowed mapping keys: 
id
, 
label
, 
command
, 
tags
— nothing else.
.facts
文件是关于项目的原子化事实声明的扁平列表。每个事实可以选择性地附带一个用于验证它的shell命令。事实清单既可以作为规范（应该满足的条件），也可以作为文档（实际满足的条件）——区别仅在于你是从哪个方向出发使用它。
- the API returns JSON
- label: project builds
  command: cargo build
- label: tests pass
  command: cargo test
  tags: [ci, core]
这就是完整的格式。简单事实使用纯字符串，当你需要命令、标签或显式ID时使用映射结构。允许的映射键包括：
id
、
label
、
command
、
tags
——没有其他键。

Essential commands

核心命令

See everything:
facts list
facts list --tags "not implemented"
facts list --has-command
Validate:
facts check
facts check --tags "ci"
check
is your primary feedback loop. It lints the files first (aborting on structural errors), then runs every command-fact and reports pass/fail/manual. Run it often. Exit 0 means all command-facts pass; manual facts don't affect the exit code.
Add facts:
facts add "users can sign up" --section features/auth
facts add "signup returns 201" --command "curl -s -o /dev/null -w '%{http_code}' localhost:3000/signup | grep 201" --section features/auth
Edit facts:
facts edit <id> --add-tag "implemented"
facts edit <id> --remove-tag "blocked"
facts edit <id> --label "corrected statement"
facts edit <id> --command "new check command"
Prefer 
--add-tag
/ 
--remove-tag
over 
--tags
. The latter replaces all tags silently — use it only when you intend a full replacement.
Remove facts:
facts remove <id>
Scaffold a new project:
facts init
Run 
facts <command> --help
for the full flag reference.
查看所有内容：
facts list
facts list --tags "not implemented"
facts list --has-command
验证事实：
facts check
facts check --tags "ci"
check
是你的主要反馈环节。它会先校验文件（若存在结构错误则终止），然后运行所有带命令的事实并报告通过/失败/手动验证状态。请经常运行该命令。退出码0表示所有带命令的事实均通过；手动验证的事实不影响退出码。
添加事实：
facts add "users can sign up" --section features/auth
facts add "signup returns 201" --command "curl -s -o /dev/null -w '%{http_code}' localhost:3000/signup | grep 201" --section features/auth
编辑事实：
facts edit <id> --add-tag "implemented"
facts edit <id> --remove-tag "blocked"
facts edit <id> --label "corrected statement"
facts edit <id> --command "new check command"
优先使用
--add-tag
/ 
--remove-tag
而非
--tags
。后者会静默替换所有标签——仅当你需要完全替换标签时才使用它。
删除事实：
facts remove <id>
初始化新项目：
facts init
运行
facts <command> --help
查看完整的参数说明。

How facts work

facts的工作机制

Files: 
.facts
is the default. Additional sheets use semantic names (
cli.facts
, 
api.facts
). All 
*.facts
files in the project root are discovered automatically.
Sections: Markdown headings (
#
, 
##
, etc.) create hierarchical sections addressable by path (e.g. 
cli/subcommands
). Sections are created when you add to them and removed when their last fact is deleted.
Tags: 
@word
tokens for filtering. Inline for plain strings (
- some fact @mvp
), 
tags:
key for mappings. Stripped from the label before display and ID hashing. Filter with boolean expressions: 
--tags "mvp and not blocked"
.
Lifecycle tags: Three well-known tags drive the agent workflow:
  • @draft
    — rough idea, needs refinement and atomization
  • @spec
    — precise and actionable, ready to implement
  • @implemented
    — true and backed by code
  • Untagged facts are ground truth — verified against the codebase
The lifecycle flows 
@draft → @spec → @implemented
. Each companion skill owns one transition.
IDs: Every fact gets a short ID (3+ chars) derived from its label hash. Stable as long as the label doesn't change. Use 
--id
or 
--new-id
to override.
Validation: Commands run via 
$SHELL
(fallback 
sh
) in the project root. Exit 0 = fact holds. Write commands that are fast and idempotent — they run on every check.
文件： 默认文件为
.facts
。额外的事实清单使用语义化名称（如
cli.facts
、
api.facts
）。项目根目录下所有
*.facts
文件会被自动识别。
章节： Markdown标题（
#
、
##
等）会创建可通过路径访问的层级章节（如
cli/subcommands
）。当你向章节添加事实时，章节会自动创建；当章节最后一个事实被删除时，章节也会被移除。
标签： 用于过滤的
@word
标记。纯字符串事实可直接内联使用（如
- some fact @mvp
），映射结构则使用
tags:
键。标签会在显示和ID哈希计算前从标签文本中剥离。可通过布尔表达式过滤：
--tags "mvp and not blocked"
。
生命周期标签： 三个知名标签用于驱动Agent工作流：
  • @draft
    ——初步想法，需要细化和原子化
  • @spec
    ——精确且可执行，已准备好实现
  • @implemented
    ——已验证为真且有代码支撑
  • 未标记的事实为基础事实——需与代码库进行验证
生命周期流转为
@draft → @spec → @implemented
。每个配套技能负责一个流转环节。
ID： 每个事实都会获得一个由标签哈希生成的短ID（3个字符以上）。只要标签不变，ID就保持稳定。可使用
--id
或
--new-id
覆盖默认ID。
验证： 命令通过
$SHELL
（ fallback为
sh
）在项目根目录运行。退出码0表示事实成立。请编写快速且幂等的命令——它们会在每次检查时运行。

Writing good facts

编写优质事实的准则

  • Atomic — one truth per fact, independently verifiable
  • Declarative — state what is true, not what to do ("uses PostgreSQL" not "set up PostgreSQL")
  • Stable — shouldn't change with every commit ("tests pass" not "there are 47 tests")
  • Verifiable — add a command when a simple check exists; manual facts are fine for things that need judgment
Good validation commands are fast, idempotent, and test one thing. Prefer 
test -f
, 
grep -q
, and short script checks over running full builds.
  • 原子化——每个事实仅包含一个独立可验证的真相
  • 声明式——陈述事实是什么，而非该做什么（如“使用PostgreSQL”而非“搭建PostgreSQL”）
  • 稳定性——不应随每次提交而变化（如“测试通过”而非“共有47个测试用例”）
  • 可验证性——当存在简单检查方式时添加命令；对于需要主观判断的内容，手动验证的事实也完全可行
优质的验证命令应快速、幂等且仅验证一件事。优先使用
test -f
、
grep -q
和简短脚本检查，而非运行完整构建。

Agent workflows

Agent工作流

Start of work — always do this first:
facts list                              # read the full spec
facts check                             # see what holds and what doesn't
Use the fact sheet to orient before writing code. It is the source of truth for what the project should look like and what is already validated.
Define the spec (most common user intent): When the user says "work on facts", "add facts", or "define the spec", they want to collaboratively define what should be true — not audit what already is.
facts add "users can sign up" --section features/auth --tags "draft"
facts add "signup returns 201" --command "curl -s ..." --section features/auth --tags "spec"
  • Discuss with the user what the project should look like
  • Add rough ideas as 
    @draft
    — they'll be refined into precise specs later
  • Add precise, actionable facts as 
    @spec
    — they're ready to implement
  • Do NOT remove 
    @draft
    or 
    @spec
    facts — they represent intended future work
  • Do NOT run 
    facts-discover
    unless the user explicitly asks to sync with reality
Track lifecycle progress:
facts list --tags "draft"               # rough ideas to refine
facts list --tags "spec"                # ready to implement
facts list --tags "implemented"         # done
facts list --tags "not implemented"     # all remaining work
facts check                             # verify
Maintain accuracy during coding work: When you add a feature, add corresponding facts. When you fix a bug, verify related facts still hold. When you remove code, remove obsolete facts.
facts check                             # find failing facts
facts edit <id> --label "corrected"     # fix inaccurate facts
facts remove <id>                       # remove obsolete facts
facts add "new truth" --section foo     # add discovered truths
工作开始时——务必先执行以下操作：
facts list                              # 阅读完整规范
facts check                             # 查看哪些事实成立、哪些不成立
在编写代码前，先通过事实清单了解项目现状。它是项目应呈现状态及已验证内容的唯一来源。
定义规范（最常见的用户需求）： 当用户提及“处理facts”、“添加facts”或“定义规范”时，他们希望协作定义项目应满足的事实——而非审核当前已有的事实。
facts add "users can sign up" --section features/auth --tags "draft"
facts add "signup returns 201" --command "curl -s ..." --section features/auth --tags "spec"
  • 与用户讨论项目应具备的特性
  • 将初步想法添加为
    @draft
    ——后续会细化为精确的规范
  • 将精确、可执行的事实添加为
    @spec
    ——这些已准备好实现
  • 不要删除
    @draft
    或
    @spec
    事实——它们代表未来的计划工作
  • 不要运行
    facts-discover
    ，除非用户明确要求与实际情况同步
追踪生命周期进度：
facts list --tags "draft"               # 需要细化的初步想法
facts list --tags "spec"                # 已准备好实现的规范
facts list --tags "implemented"         # 已完成的内容
facts list --tags "not implemented"     # 所有剩余工作
facts check                             # 验证事实
编码过程中保持准确性： 当你添加功能时，添加对应的事实。当你修复bug时，验证相关事实是否仍然成立。当你删除代码时，移除过时的事实。
facts check                             # 找出不成立的事实
facts edit <id> --label "corrected"     # 修正不准确的事实
facts remove <id>                       # 移除过时的事实
facts add "new truth" --section foo     # 添加新发现的事实

Companion skills

配套技能

Each skill owns one lifecycle transition:
  • facts-discover — scan the codebase and classify every fact by lifecycle stage (
    @draft
    , 
    @spec
    , 
    @implemented
    ). Use to triage or bootstrap.
  • facts-refine — pick up 
    @draft
    facts and refine them into precise 
    @spec
    facts with the user. Use when drafts need sharpening.
  • facts-implement — pick up 
    @spec
    facts and implement them in code, then tag 
    @implemented
    . Use when specs are ready to build.
每个技能负责一个生命周期流转环节：
  • facts-discover——扫描代码库并将每个事实按生命周期阶段（
    @draft
    、
    @spec
    、
    @implemented
    ）分类。用于分类梳理或初始化项目。
  • facts-refine——提取
    @draft
    事实并与用户协作将其细化为精确的
    @spec
    事实。当草稿需要完善时使用。
  • facts-implement——提取
    @spec
    事实并在代码中实现，然后标记为
    @implemented
    。当规范已准备好开发时使用。