git-journal

Git Journal

记录代码变更背后的“原因”。Git 会跟踪是什么、何处、何时、由谁完成——此技能记录的是原因。

此技能有两种输出：

输出	位置	用途
技术日志	journals/YYYY-MM-DD_<branch>.md	按分支记录的变更日志：权衡、替代方案、技术细节
业务文档	docs/	按功能领域编写、持续更新的当前状态 QA 文档

每次调用 git-journal 时，都会先按原样执行技术日志流程，然后评估是否需要更新业务文档。

触发短语

短语	行为
“记得写日志”	在整个会话期间持续提醒。主动考虑在重大决策后写日志；同时评估业务文档。
“有什么需要记日志吗？”	回顾会话；建议日志条目和所需的文档更新。
“把这个记到日志里”	将当前上下文记录到日志中；评估对业务文档的影响。
“更新日志”	运行日志脚本，并提示填写原因内容。
“更新文档”	运行文档脚本；提示填写业务背景；更新相关的 docs/ 文件。
“有什么需要记录成文档吗？”	检查当前工作是否需要新建或更新业务文档。

“记得写日志”模式

启用后，在整个会话期间都要留意日志记录：

• 复杂问题解决后 → 考虑记录推理过程
• 架构决策后 → 记录权衡
• 拒绝某种方案后 → 记录拒绝原因
• 提交前 → 如有尚未记录的上下文，及时提醒
• 用户可见行为发生变化后 → 评估是否需要更新 docs/

“有什么需要记日志吗？”回顾

有人询问时，检查：

1. 当前分支上最近的 git 提交
2. 本次对话中所做的代码变更
3. 讨论过的决策和权衡
4. 已实现的非显而易见的解决方案或变通方法

然后为日志提出具体条目，评估业务文档，或确认没有重要内容需要记录。

---

第 1 部分：技术日志（保持不变）

快速开始

1. 确认日志文件存在：

   python skills/git-journal/scripts/ensure_git_journal.py
   

2. 更新为当前状态：

   python skills/git-journal/scripts/update_git_journal.py
   

3. 撰写原因部分（自动化会处理由谁、何时、是什么）。

日志位置

journals/YYYY-MM-DD_<branch-name>.md

• 每个分支对应一份日志
• 使用扁平文件结构（不创建嵌套文件夹）
• 规范化分支名称（斜杠 → 连字符）

5 个 W 的优先级

1. 原因 ← 首要内容。务必记录。
2. 是什么 — 概念性摘要
3. 何处 — 受影响的关键区域
4. 由谁 — 来自 git 配置
5. 何时 — 时间戳

如果时间有限，只需确保原因部分准确。

原因部分要写什么

## Why, current summary

**Intent**
- Refactored auth to support background token refresh

**Constraints**
- Must work offline after initial auth

**Tradeoffs**
- Added complexity for better UX

**Alternatives considered**
- Redux approach: rejected due to complexity

**Non-obvious nuance**
- Retry loop looks like a bug but handles edge case where...

请包含：

• 要解决的问题
• 选择此方案的原因
• 约束（时间、平台、API、业务）
• 被拒绝的替代方案及原因
• 看起来有问题、实际却正确的内容

日志结构

分为两层：

• 顶部：汇总摘要（定期整合）
• 底部：详细日志（只追加带时间戳的条目）

---

第 2 部分：业务 QA 文档

用途

docs/ 记录的是产品从业务角度出发的当前状态，而不是变更日志。日志记录增量式的技术推理；文档则按功能领域汇总内容，让 QA、AI Agent 和未来的 Notion 同步能够回答：产品应该如何表现，为什么？

文档位置

docs/
  _index.md                 # Master entry: taxonomy, app matrix
  <domain>/
    _index.md               # Domain overview, sub-feature links
    <feature>.md            # Feature detail (when enough content warrants a file)

分类规则：

• 按业务领域组织（auth、shop、arena），而不是按分支或技术层
• 根据分支/包名提示映射目录：feat-auth → auth/，feat-shop → shop/，等等
• 工作涉及新的业务领域时，创建新的领域文件夹
• 仅在存在独立细节时才拆分为 <feature>.md；否则将内容保留在领域 _index.md 中
• 文件夹名称使用小写字母和连字符（例如，attend2earn、watch2earn）

Apps 和 applies_to

务必确认适用的应用。有效值：

值	含义
wunderfan	仅 Wunderfan
wunderpar	仅 Wunderpar
golf-champs	仅 Golf Champs
wunderfan、wunderpar	共享（常见组合）
all	所有应用

使用 YAML frontmatter applies_to: [wunderfan, wunderpar]。各应用的差异放在 ## App-Specific Behavior 下，使用 ### Wunderfan、### Wunderpar 等标题——不要重复整篇文档。

功能文件格式

创建新的功能文件时，使用 assets/docs-feature-template.md。必需的 frontmatter：

---
domain: auth
feature: sign-in
applies_to: [wunderfan, wunderpar]
last_updated: YYYY-MM-DD
---

各章节应使用面向意图的语言，而非实现细节：

• 业务意图 — 解决的问题，以及功能存在的原因
• 用户体验 — 用通俗语言描述顺利流程
• 业务规则 — 约束行为的规则
• 验收标准 — Given/When/Then 或可测试的检查清单
• 按应用划分的行为 — 各应用之间的差异
• 边缘情况 — 失败路径、边界条件
• 待解决问题 — 尚未解决的事项；回答后标记为 [Resolved YYYY-MM-DD]

每当内容发生变化时，更新 last_updated。文档中不要引用日志——日志是变更记录，文档描述的是当前状态。

业务文档快速入门

1. 确认文档脚手架已存在：

   python skills/git-journal/scripts/ensure_docs.py
   

2. 检查分类体系（为 Agent 提供上下文）：

   python skills/git-journal/scripts/update_docs.py --list
   

3. 创建或更新领域/功能文件（由 Agent 编写内容；脚本可搭建脚手架）：

   python skills/git-journal/scripts/update_docs.py --domain auth --feature sign-in
   

增强流程（每次调用日志时）

1. Technical journal     → ensure + update + write Why (existing flow)
2. Analyze changes       → user-facing vs purely technical?
3. Map taxonomy          → which domain(s)? new domain?
4. Load existing docs    → ensure_docs.py if needed
5. Assess impact         → business change? if no, skip docs
6. Prompt user           → question framework (below); never guess
7. Update docs           → merge into current-state files; set last_updated
8. Staleness check       → flag docs that may contradict current work
9. Update root _index.md → taxonomy + app matrix from frontmatter

纯技术变更（重构、依赖升级、不会改变用户体验的内部重命名）→ 仅更新日志；除非怀疑文档已过时，否则跳过文档更新。

问题框架

只询问必要的问题——不要每次都逐项盘问。

始终询问（如果尚不清楚）：

• 适用于哪些应用？（Wunderfan / Wunderpar / Golf Champs / 所有应用）

新功能或新领域：

• 这为用户解决了什么业务问题？
• 用户体验是什么样的？（顺利流程）
• 哪些业务规则约束此行为？
• 从用户的角度来看，怎样才算成功？

更新现有功能：

• 此变更会影响面向用户的行为，还是纯技术变更？
• 是否会影响任何现有业务规则？
• 适用的应用是否发生变化？

可能已过时：

• [domain] 的文档描述了 [behavior X]。这是否因你当前的工作而发生变化，还是仍然准确？

上下文不明确：

• 发生 [edge case] 时具体会怎样？
• [assumption from existing docs] 是否仍然有效？

如果用户无法回答，请在文档中记录为待解决问题——不要臆造业务规则。

根目录 _index.md

维护以下内容：

• 分类体系 — 包含指向 _index.md 或功能文件链接的领域表格
• 应用矩阵 — 各领域/功能适用于哪些应用（根据 frontmatter 生成）
• 上次刷新时间 — 重新生成索引的日期

文档变更后，不带标志运行 update_docs.py 以刷新索引。

---

集成

可使用 references/cursor-rule-template.md 中现成的 Cursor 规则。

可选的提交前钩子：

#!/bin/sh
python skills/git-journal/scripts/ensure_git_journal.py
python skills/git-journal/scripts/ensure_docs.py

文件

日志（保持不变）：

• scripts/ensure_git_journal.py — 若日志不存在则创建
• scripts/update_git_journal.py — 更新 Who/When/What
• assets/git-journal-template.md — 新日志模板

业务文档：

• scripts/ensure_docs.py — 若 docs/ 和根目录 _index.md 不存在，则创建
• scripts/update_docs.py — 分类列表、领域/功能脚手架、索引刷新
• assets/docs-index-template.md — 根目录 docs/_index.md 模板
• assets/docs-domain-template.md — 领域 docs/<domain>/_index.md 模板
• assets/docs-feature-template.md — 功能文件模板

共享：

• references/cursor-rule-template.md — Cursor 规则模板