lore-commits

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Lore Commits

Overview

概述

Every commit destroys decision context. You considered alternatives, evaluated tradeoffs, and chose one approach — but only the final diff survives. Lore reclaims this lost knowledge by encoding it as git trailers in commit messages.

Core principle: A commit is not a label for a diff — it's an atomic unit of institutional knowledge. Use git's native trailer format so decisions are machine-queryable, not buried in prose.

每次提交都会丢失决策上下文。你曾考虑过多种方案、评估过权衡利弊，最终选择了一种方法——但只有最终的差异留存了下来。Lore通过在commit消息中以git trailers的形式编码这些丢失的知识，将其重新找回。

**核心原则：**提交不是差异的标签——它是机构知识的原子单元。使用git原生的trailer格式，让决策可被机器查询，而不是埋没在散文式的文本中。

When to Use

使用场景

Any commit where you made non-obvious decisions
When you rejected alternative approaches
When external constraints shaped your implementation
When future modifiers need warnings about fragile assumptions
When test coverage has known gaps

When NOT to use: Trivial changes (typo fixes, formatting) where no real decisions were made.

任何涉及非显而易见决策的提交
当你否决了其他备选方案时
当外部约束条件影响了你的实现方式时
当后续修改者需要了解关于脆弱假设的警告时
当测试覆盖存在已知缺口时

**不适用场景：**无实质决策的微小变更（如拼写错误修复、格式调整）。

The Format

格式规范

<imperative summary line>

<optional body explaining the change>

Constraint: <external constraint that shaped this decision>
Rejected: <alternative> | <reason it was rejected>
Confidence: <high | medium | low>
Scope-risk: <narrow | moderate | broad>
Reversibility: <clean | moderate | difficult>
Directive: <warning or instruction for future modifiers>
Tested: <what was verified>
Not-tested: <known coverage gaps>
Related: <commit hash or description of related commit>

All trailers are optional. Include only those that carry signal for this specific commit.

<祈使语气的摘要行>

<可选的变更说明正文>

Constraint: <影响决策的外部约束条件>
Rejected: <备选方案> | <否决理由>
Confidence: <high | medium | low>
Scope-risk: <narrow | moderate | broad>
Reversibility: <clean | moderate | difficult>
Directive: <给后续修改者的警告或说明>
Tested: <已验证的内容>
Not-tested: <已知的测试覆盖缺口>
Related: <相关提交的哈希值或描述>

所有trailer均为可选。仅添加与当前提交相关且有实际意义的trailer。

Trailer Vocabulary

Trailer 词汇说明

Trailer	Purpose	Example
`Constraint:`	External limit that shaped the decision	`Auth service does not support token introspection`
`Rejected:`	Alternative considered and why it was dropped. Use `	` to separate alternative from reason
`Confidence:`	How sure you are this is right: `high` , `medium` , `low`	`high`
`Scope-risk:`	Blast radius: `narrow` , `moderate` , `broad`	`narrow`
`Reversibility:`	How easy to undo: `clean` , `moderate` , `difficult`	`clean`
`Directive:`	Warning to future modifiers — what NOT to do or what to check first	`Do not narrow 4xx handling without verifying upstream behavior`
`Tested:`	What was verified and how	`Single expired token refresh (unit)`
`Not-tested:`	Known gaps in verification	`Auth service cold-start > 500ms behavior`
`Related:`	Linked commits forming a decision chain	`abc1234 (initial auth interceptor)`

You can repeat trailers (multiple

Constraint:

, multiple

Rejected:

, etc.).

You can extend the vocabulary with custom trailers when needed (e.g.,

Deadline:

Stakeholder:

Migration:

Trailer	用途	示例
`Constraint:`	影响决策的外部限制条件	`Auth service does not support token introspection`
`Rejected:`	曾考虑但被否决的方案及理由。使用`	`分隔方案与理由
`Confidence:`	对决策正确性的确定程度： `high` , `medium` , `low`	`high`
`Scope-risk:`	影响范围： `narrow` , `moderate` , `broad`	`narrow`
`Reversibility:`	撤销难度： `clean` , `moderate` , `difficult`	`clean`
`Directive:`	给后续修改者的警告——哪些操作不能做或需要优先检查的内容	`Do not narrow 4xx handling without verifying upstream behavior`
`Tested:`	已验证的内容及方式	`Single expired token refresh (unit)`
`Not-tested:`	已知的验证缺口	`Auth service cold-start > 500ms behavior`
`Related:`	构成决策链的关联提交	`abc1234 (initial auth interceptor)`

你可以重复使用trailer（多个

Constraint:

、多个

Rejected:

等）。

必要时你可以扩展词汇，添加自定义trailer（如

Deadline:

、

Stakeholder:

、

Migration:

）。

Complete Example

完整示例

Prevent silent session drops during long-running operations

The auth service returns inconsistent status codes on token
expiry, so the interceptor catches all 4xx responses and
triggers an inline refresh.

Constraint: Auth service does not support token introspection
Constraint: Must not add latency to non-expired-token paths
Rejected: Extend token TTL to 24h | security policy violation
Rejected: Background refresh on timer | race condition
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Error handling is intentionally broad (all 4xx)
  -- do not narrow without verifying upstream behavior
Tested: Single expired token refresh (unit)
Not-tested: Auth service cold-start > 500ms behavior

Prevent silent session drops during long-running operations

The auth service returns inconsistent status codes on token
expiry, so the interceptor catches all 4xx responses and
triggers an inline refresh.

Constraint: Auth service does not support token introspection
Constraint: Must not add latency to non-expired-token paths
Rejected: Extend token TTL to 24h | security policy violation
Rejected: Background refresh on timer | race condition
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Error handling is intentionally broad (all 4xx)
  -- do not narrow without verifying upstream behavior
Tested: Single expired token refresh (unit)
Not-tested: Auth service cold-start > 500ms behavior

Why Git Trailers (Not Prose)

为什么选择Git Trailers而非散文式文本

Agents naturally capture decision context as prose paragraphs. The problem: prose is not queryable.

Git trailers are a native git feature. Queryable with standard git tools:

bash

undefined

Agent通常会以散文段落的形式记录决策上下文。但问题在于：散文式文本无法被查询。

Git trailers是git的原生功能，可通过标准git工具查询：

bash

undefined

Query all constraints affecting a file

查询影响某文件的所有约束条件

git log --all --grep="^Constraint:" -- path/to/file.ts

Find all rejected approaches

查找所有被否决的方案

git log --all --grep="^Rejected:" -- path/to/file.ts

Find directives (warnings for future modifiers)

查找给后续修改者的指导说明

git log --all --grep="^Directive:" -- path/to/file.ts

Check what's not tested

查看未测试的内容

git log --all --grep="^Not-tested:" -- path/to/file.ts


This turns your git history into a **queryable decision database** at zero infrastructure cost.

git log --all --grep="^Not-tested:" -- path/to/file.ts


这无需额外基础设施成本，就能将你的git历史转化为**可查询的决策数据库**。

Agent Workflow

Agent 工作流

When modifying code, before committing:

Harvest context — What constraints did you face? What alternatives did you reject?
Write the summary line — Imperative, focused on why not what
Add body if the how needs explanation
Append trailers — One per decision fact. Only include trailers that carry signal.
Self-check — Would a future agent modifying this code benefit from knowing this?

修改代码后，提交前请执行以下步骤：

收集上下文——你面临了哪些约束条件？否决了哪些备选方案？
撰写摘要行——使用祈使语气，聚焦于原因而非内容
如有需要，添加正文——解释实现方式
追加trailer——每个决策事实对应一个trailer。仅添加有实际意义的trailer。
自我检查——后续修改此代码的Agent是否会从这些信息中受益？

Common Mistakes

常见错误

Mistake	Fix
Writing trailers as prose paragraphs	Use `Key: value` format on separate lines
Putting trailers before the body	Trailers must come after the body, separated by a blank line
Omitting the reason in `Rejected:`	Always use `alternative
Adding trailers to trivial commits	Only add when real decisions were made
Duplicating diff content in trailers	Trailers capture what's NOT in the diff — the why, not the what
Using `Confidence: yes`	Use the scale: `high` , `medium` , `low`

错误	修正方式
将trailer写成散文段落	使用 `Key: value` 格式，单独成行
将trailer放在正文之前	trailer必须放在正文之后，用空行分隔
`Rejected:` 中遗漏理由	始终使用`备选方案
给微小变更添加trailer	仅在存在实质决策时添加
在trailer中重复差异内容	trailer应记录差异中没有的信息——即原因，而非内容
使用 `Confidence: yes`	使用标准级别： `high` , `medium` , `low`