用途:Lore Commits 用于在编写非平凡改动的 Git 提交信息时,把决策背景编码为 Git trailer,避免只留下最终 diff 而丢失“为什么这样改”的信息。其核心理念是:提交不是 diff 的标签,而是机构知识的原子单元。
主要能力:支持一组 trailer 词汇,包括 Constraint(外部约束)、Rejected(被否决的替代方案及原因)、Confidence(high/medium/low)、Scope-risk(narrow/moderate/broad)、Reversibility(clean/moderate/difficult)、Directive(对未来修改者的警告或指令)、Tested(已验证内容)、Not-tested(已知覆盖缺口)、Related(相关提交)。所有 trailer 均可选,可重复,也可按需扩展自定义 trailer。
使用方式:提交信息先写祈使句摘要行,可选正文解释改动,然后空一行追加 trailer,每行一个 Key: value。例如:Constraint: Auth service does not support token introspection;Rejected: Extend token TTL to 24h | security policy violation。可用标准 git 工具查询,如 git log --all --grep="^Constraint:" -- path/to/file.ts,也可替换为 Rejected、Directive、Not-tested 等。
适用场景:做出了非显而易见决策的提交、否决了替代方案、外部约束影响实现、需要提醒未来修改者注意脆弱假设、测试覆盖存在已知缺口时。
限制:琐碎改动(拼写修复、格式化)不应使用;trailer 必须位于正文之后并用空行分隔;Rejected 需用 | 分隔方案与原因;Confidence 只能取 high、medium、low;不要用 trailer 重复 diff 内容,而应记录 diff 中没有的“为什么”。