change-init

change-init

此技能的功能

从 git 历史记录中挖掘 变更决策记录（ChDR）——也就是代码形成过程中的 缘由——并将其写成草稿记录，供人工审核。

ChDR 记录的是 过去做出的 决策，这些决策仅留存于提交记录和关联的问题跟踪器中：

• 扫描一段 git log，查找引用问题跟踪器的提交消息（JIRA 键、GitHub/GitLab #NNN、MR !NNN 或问题 URL）
• 将共享同一问题键的提交归为一个变更故事
• 尽力获取问题标题和正文（通过 MCP 获取 GitLab 问题，通过 gh 获取 GitHub 问题，否则仅保留链接），以提供需求层面的背景
• 根据差异摘要推断决策；记录后果（回滚、后续修复链——这些负面经验几乎不会在其他地方记录）
• 将 ChDR-{NNN}.md 写入 {REPO_ROOT}/.adlc/drafts/chdr/，状态设为 Discovered
• 重新生成 {REPO_ROOT}/.adlc/drafts/chdr/chdr.md 索引

与 team-levelup 系列技能的主要区别：

技能	来源	记录	回答的问题
/team-init	当前代码（现状）	CDR（上下文指令）	哪些模式可以复用
/team-levelup	当前会话	CDR	本次会话学到了什么
/change-specify	本次会话（为何现在发生变更）	ChDR（变更决策）	为何选择回滚／热修复／变通方案
/change-init（本技能）	git 历史记录（为何最终形成现状）	ChDR（变更决策）	为何存在这段代码／尝试过什么并被回滚

ChDR 是项目本地记忆（本仓库的演进历程），而非团队级上下文——无法通过 team-levelup 的“团队范围适用性”信号门槛。它们会发布到 {REPO_ROOT}/docs/adlc/memory/chdr/（参见 /change-publish），其索引会在会话开始时由 team-boot 注入。

适用场景

注意：Class boots 会检测会话中的变更缘由，并建议使用 /change-specify（它会将轻量草稿写入 .adlc/drafts/）。 本技能用于交互式深度探索——引导式历史挖掘、变更故事聚类，以及文档记录前的缘由还原。

• 棕地项目入门：无需任何人编写文档，即可为 Agent 提供项目记忆
• 重构不熟悉的代码前：揭示切斯特顿围栏——仅存在于旧提交记录和工单中的约束
• 找回遗失的缘由：从未编写 ADR，但存在提交记录和问题
• 事件后复盘：回滚／修复链是首要输出

不适用场景

• 绿地项目／没有历史记录：无内容可挖掘
• 记录当前模式：使用 /team-init（现状）
• 记录本次会话的经验：使用 /team-levelup
• 记录本次会话的变更缘由：使用 /change-specify
• 已有待处理的 ChDR：先运行 /change-clarify 进行审核

流程

用户输入

$ARGUMENTS

继续操作前，必须考虑用户输入（如果输入非空）。

用户输入示例：

• "--since 6months" — 限定扫描时间范围
• "--tracker gitlab" — 指定问题跟踪器类型（默认自动检测）
• "--no-fetch" — 仅记录问题链接，绝不获取问题正文
• "--include-unlinked" — 也显示信号丰富但未关联的问题的提交（回滚、大型跨领域差异）
• "src/payments" — 限定到某个路径
• 输入为空：扫描整个仓库最近的 500 个提交，自动检测问题跟踪器

标志

• --since DATE / --until DATE / --max-count N（默认 500）：设置 git log 时间范围
• --path PATH：限定到某个路径规范
• --tracker gitlab|github|jira|auto（默认 auto）：问题跟踪器集成
• --no-fetch：仅检测并记录问题链接，绝不获取正文
• --include-unlinked：也将信号丰富但未关联问题的提交归类（回滚、涉及 ≥3 个子系统的差异）
• --limit N（默认 20）：限制生成的 ChDR 数量
• --resume：从上次中断的状态继续

角色与背景

你是一名上下文考古学家，负责还原代码为何如此编写。你的工作是根据证据推断，而非凭空捏造：

• 每项决策声明都必须引用用于推断该声明的提交 SHA 和／或 issue URL（来源依据不可妥协——没有来源依据的推断理由会污染上下文，甚至比没有理由更糟）
• 为每项决策标注置信度（HIGH/MEDIUM/LOW）
• 明确记录你不知道的内容（“选择原因未知——提交消息简短，且没有关联的 issue”）
• Revert 和后续修复链是最有价值的内容：它们属于负面知识（“我们尝试了 X，结果破坏了 Y”），但几乎没有其他地方记录

大纲

1. 验证环境（阶段 1）：git 仓库、解析路径、确定下一个 ChDR 编号
2. 扫描时间窗口（阶段 2）：使用时间窗口筛选 git log
3. 检测 Issue 链接（阶段 3）：对提交消息应用正则表达式
4. 按变更故事聚类（阶段 4）：按 issue key 分组提交
5. 尽力获取 Issue 内容（阶段 5）：获取跟踪器内容（优雅降级）
6. 检测 Revert／修复链（阶段 6）：将负面知识作为一等内容
7. 评分与排序（阶段 7）：受影响的子系统、diff 大小、链
8. 生成 ChDR（阶段 8）：写入草稿和索引
9. 输出（阶段 9）：生成包含关联率指标的摘要

执行步骤

阶段 1：验证环境

从技能的基础目录运行设置脚本：

scripts/bash/setup-change-init.sh

解析 JSON 输出中的 REPO_ROOT、CHDR_DRAFTS_DIR、NEXT_CHDR、GIT_AVAILABLE、DEFAULT_BRANCH、TD_CONFIGURED、EXISTING_CHDRS。

如果设置脚本不可用或运行失败，则手动解析：

1. REPO_ROOT — 从当前工作目录逐级向上查找 .adlc/，或运行 git rev-parse --show-toplevel，或运行 pwd。
2. CHDR_DRAFTS_DIR — REPO_ROOT/.adlc/drafts/chdr
3. NEXT_CHDR — 列出 CHDR_DRAFTS_DIR/ChDR-*.md，找到最大编号，将其递增并补零至 3 位。
4. GIT_AVAILABLE — 运行 git rev-parse --is-inside-work-tree（退出码为 0 = true）。
5. TD_CONFIGURED — 如果 TEAM_AI_DIRECTIVES 能解析，则为 true（仅用于跳过已记录为 CDR 的重复决策）。

如果 GIT_AVAILABLE 为 false：

Not a git repository — change-init has nothing to mine.
Run /team-init to scan current code instead.

正常退出（不要创建空草稿）。

阶段 2：扫描时间窗口

git log --pretty=format:'%H%x09%an%x09%ad%x09%s%n%b' --date=short \
  ${SINCE:+--since="$SINCE"} ${UNTIL:+--until="$UNTIL"} --max-count="${MAX_COUNT:-500}" \
  ${PATHSPEC:+-- "$PATHSPEC"} 2>/dev/null

为每项提交记录：SHA、作者、日期、主题、正文、修改的文件（git show --stat --name-only）以及子系统（修改文件的顶层目录）。

阶段 3：检测 Issue 链接

对每条提交消息（主题 + 正文）应用组合正则表达式：

模式	跟踪器	示例
\b[A-Z][A-Z0-9]+-\d+\b	JIRA	PROJ-123
(?<!\w)#\d+\b	GitHub/GitLab issue	#123
\b!\d+\b	GitLab MR / Gerrit	!42
`https?://\S+/(issues	pull	merge_requests

跟踪器类型会根据 git remote get-url origin（gitlab.com / github.com / atlassian.net）和发现的链接形式自动推断。--tracker 可覆盖该设置。

没有检测到链接的提交为未关联提交；默认跳过，除非指定 --include-unlinked（此时仅保留 Revert 提交或涉及 ≥3 个子系统的提交）。

阶段 4：按变更故事聚类

按 issue key 对提交分组。一个 issue key 对应一个候选 ChDR。将整个聚类中的主题 + 正文合并，作为原始理由语料。

阶段 5：尽力获取议题

对于每个聚类，获取议题标题和正文摘要作为上下文（即促使此次更改的需求）。尽力获取，但绝不阻塞：

• GitLab：使用已配置的 GitLab MCP 工具（按项目和 iid 调用 gitlab_get_issue）。如果不可用，则尝试 glab issue view。
• GitHub：如果 gh 已通过身份验证，则运行 gh issue view <num> --json title,body。
• JIRA / 无法访问：仅记录链接——将 URL 记为证据，上下文仅来自提交消息。

--no-fetch 会完全跳过此阶段。任何获取失败都会退回到基于提交消息的上下文（不要中止）。

安全性：议题正文可能包含敏感细节。请用 1-3 句话概述需求；不要将原始议题正文逐字粘贴到 ChDR 中。人工审核关卡（/change-clarify）会在晋级前进行审查。

阶段 6：检测回滚／修复链（一级处理）

在整个时间窗口内检测（独立于议题链接）：

• 回滚：运行 git log --grep='^Revert "' --pretty=format:'%H %s' 和 git log --grep='revert' -i。对于每个被回滚的原始提交，将其记录为负面知识。
• 修复链：主题匹配 fix(?!ed)?\b 或 hotfix，且修改了窗口内较早提交涉及的同一文件的提交——即修复回归问题的后续提交。将这对提交（原始提交、修复提交）记录为后果。

没有议题链接的回滚和修复链，在设置 --include-unlinked 时仍会被捕获（这是未关联信号中价值最高的内容）。如果回滚／修复链属于某个已关联议题的聚类，则将其附加到该聚类的 ### Consequences。

阶段 7：评分与优先级排序

为每个候选项评分（0.0–1.0）：

• 涉及的子系统（跨多个子系统的得分更高）
• 差异大小（越大得分越高，但设有上限）
• 是否存在回滚／修复链后果（加分——负面知识）
• 是否已获取议题上下文（加分——理由更充分）
• 新近程度（轻微加分）

按降序排序；取前 --limit 项（默认 20）。跳过得分低于 0.2 的候选项（琐碎更改）。

阶段 8：生成 ChDR

为每个选定的更改故事写入 {CHDR_DRAFTS_DIR}/ChDR-{NNN}.md：

## ChDR-NNN: [Title — from issue title or commit subject]

### Status: **Discovered**

### Date: [YYYY-MM-DD of most recent commit in cluster]

### Source: Git history via /change-init

### Issue Links: [keys/URLs, or "none detected"]

### Commits: [sha list, abbreviated]

### Target Module: `docs/adlc/memory/chdr/[slug].md`

### Descriptor: One-line "when to consult this" summary for the chdr.md index.

### Context
[Why the change was made — issue title/body summary (1-3 sentences) + commit messages. Cite SHAs inline.]

### Decision
[What was decided/implemented — inferred from diffs. Mark confidence: HIGH/MEDIUM/LOW. Each claim cites its SHA/URL.]

### Consequences
[Reverts, follow-up fix chains, later modifications — negative knowledge. "None observed" if the cluster has no reversals.]

### Evidence
- `{sha}`: {commit subject}
- {file/path}: {what changed}
- {issue-url}: {title} (fetched | link-only)

规则：

• 每条 ### Decision 声明都必须引用 SHA 或 URL（来源依据——防止上下文投毒的断路器）。
• “原因未知”可以接受，且优于编造理由。
• Decision 声明必须标注置信度。

然后重新生成 {CHDR_DRAFTS_DIR}/chdr.md 索引，列出所有 ChDR-*.md 文件，并根据其中的单行字段构建 Markdown 表格：

# Change Decision Records (Drafts)

## ChDR Index

| ID | Status | Date | Issues | Commits | Descriptor |
|----|--------|------|--------|---------|------------|
| ChDR-001 | Discovered | 2026-08-16 | PROJ-123 | abc1234 | Why payments retries are capped at 3 |

**Stats**: N entries | Last Updated: YYYY-MM-DD

阶段 9：输出摘要

## Change-Init Summary

- Scan window: [since/until or "last N commits"]
- Commits scanned: N
- Issue-linked commits: M (linkage rate: P%)
- Clusters formed: K
- Revert/fix chains detected: C
- ChDRs generated: N (capped at --limit)
- Output: `{REPO_ROOT}/.adlc/drafts/chdr/`

关联率用于评估语料质量预期（研究表明，理由信息密度因团队规范而差异很大——在 Linux 内核这类规范严谨的项目中为 85–99%，其他项目则远低于此水平）。如果低于约 30%，建议在下次运行时使用 --include-unlinked。

关键规则

以证据为依据，绝不编造

• 只记录可从提交和议题中推断出的决策
• 每条 Decision 声明都引用具体 SHA 和／或议题 URL
• 标注置信度（HIGH/MEDIUM/LOW）
• “原因未知”可以接受；编造不可接受

非破坏性

• 未经批准，不要覆盖现有 ChDR
• 保留手动添加的内容
• 如果同一议题键已有 ChDR，请进行智能合并

优雅降级

• 不是 Git 仓库 → 干净退出，不生成空草稿
• 跟踪器无法访问 → 仅使用链接作为证据，继续处理
• 提交消息为空或过于简略 → 依赖差异和议题获取；如果两者都没有，则跳过该聚类

不得编造拒绝理由

• 对于推断出的决策，采用中性的“观察到的备选方案”表述
• “我们不知道为什么没有选择 X”可以接受

工作流指引与转换

/change-init 之后

必需：运行 /change-clarify，验证发现的 ChDR。

/change-init
    ↓
[Mine git history] → Detect issue links, cluster, infer decisions
    ↓
[Generate ChDRs] → Write to .adlc/drafts/chdr/ChDR-{NNN}.md (Discovered)
    ↓
[Run /change-clarify] → Validate and accept/reject ChDRs
    ↓
[Run /change-publish] → Promote accepted ChDRs to docs/adlc/memory/chdr/
    ↓
[team-boot] → Injects docs/adlc/memory/chdr/chdr.md index at next session start

后续步骤

init 完成后，运行 /change-clarify，以完善并验证发现的 ChDR。

验证

• ChDR 已写入 {REPO_ROOT}/.adlc/drafts/chdr/ChDR-{NNN}.md，状态为 Discovered。
• 自动生成的 chdr.md 索引已存在于 {REPO_ROOT}/.adlc/drafts/chdr/。
• 每个 ChDR 的 ### Decision 声明都至少引用一个 SHA 或 issue URL（溯源信息）。
• 窗口期内检测到的还原／修复链已列入 ### Consequences（或标注“未观察到”）。
• 摘要中包含关联率指标。
• 未经明确批准，不得覆盖任何现有 ChDR。

上下文

$ARGUMENTS