概述
提交信息只告诉你「改了什么」，why 告诉你「为什么这么改」。它在本地运行 `git log -L` 找出修改过目标行（或文件）的所有提交，再逐条取回每次提交在 AIFlare 中保存的捕获——意图、备选方案、对话、diff 元数据——并按最新提交在上的顺序拼接成时间线返回。没有捕获的提交会落到回退分支，仅返回提交列表。
使用场景
在动手修改 AI 写下的代码之前先查一下意图——在已记录的依据上调试或重构，而不是靠猜测。
当某一行看起来不对时，通过该提交记录的意图与被否决的备选方案，判断它到底是有意为之的 workaround 还是真正的错误。
在重构不是自己写的代码之前，先调出形成该代码的约束与权衡，避免破坏看不见的契约。
在不是自己写的模块里追踪某一行的诞生过程，连同每次提交背后的对话片段一起读。
AI 智能体在打补丁前应当先调用 `why`，把自己（或另一个智能体）的过去意图查出来，再决定要不要动。
使用方法
语法
在 Claude Code 中用斜杠命令调用，或者让智能体直接调用工具。在文件路径后加 `:<line>` 即可只追踪某一行。
/why <file>[:<line>]参数
| 名称 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| file | string | 必填 | - | 要查询的文件路径（相对于 git 根目录，或绝对路径）。 |
| line | number | 可选 | - | 要解释的行号。省略则使用文件的完整历史（同样限制为最近 5 个提交）。 |
处理流程
常见错误
`aiflare.yml` 不存在或 `api_key` 为空时，返回「AIFlare is not configured. Place aiflare.yml in your project root.」。
无法定位 git 根目录时，返回「Not in a git repository.」。
文件不存在或行号超范围时，返回「git query failed — check the file path …」。
输出格式
返回 Markdown 字符串。有捕获和无捕获两种形态。
每个提交以卡片形式呈现，依次显示 Title / Tag / Intent / Alternatives considered / Diff around this line / Conversation behind this commit。最新提交在上；只有 1 条捕获时标签为 `only`，多条时为 `latest / earlier / oldest`。
存在提交但 AIFlare 中无任何捕获时使用。提示「N commits touched this line, but none are captured in AIFlare.」，并列出提交哈希·日期·subject。（在引入 AIFlare 前或在 Claude Code 之外的提交）
当相关提交超过 5 个时，时间线会附加「Showing the 5 most recent of N commits.」，回退则附加「Checked the 5 most recent of N commits, but none are captured in AIFlare.」。
错误与回退
所有错误都作为工具响应文本返回，绝不会中断 Claude Code 会话。智能体读到提示后，自然地继续常规调试流程。
| 情形 | 返回文本 |
|---|---|
| 未配置 AIFlare | AIFlare is not configured. Place aiflare.yml in your project root. |
| 不在 git 仓库 | Not in a git repository. |
| git log 失败（路径或行号错误） | git query failed — check the file path … |
| 无提交历史 | No commit history found for {file}:{line}. （或 …for {file}.） |
| 后端超时 / 网络错误 | Error querying AIFlare: {message} |
| 某次提交的 git show 失败 | 仅省略该提交的 diff 段，其余时间线照常返回。 |