backward-traceability

向后追溯

让最终 PDF 中的每个数字都能链接回生成它的确切代码行。

输入

• $0 — 包含代码和 LaTeX 文件的论文项目目录

参考资料

• 追溯模式和 LaTeX 命令：~/.claude/skills/backward-traceability/references/traceability-patterns.md

脚本

扫描 hypertarget/hyperlink 引用

python ~/.claude/skills/backward-traceability/scripts/ref_numeric_values.py \
  --scan paper/main.tex --output report.json

报告：所有 hypertarget、超链接、孤立引用和未引用的数值。

验证交叉引用完整性

python ~/.claude/skills/backward-traceability/scripts/ref_numeric_values.py \
  --verify paper/main.tex --code-output results.txt

交叉核对论文正文与代码输出中的数值，并报告不匹配项。

工作流

步骤 1：为代码输出添加标签

为实验代码生成的每个数值添加 hypertarget 标签：

# In experiment code output:
print(f"\\hypertarget{{R1a}}{{45.3}}")  # Mean accuracy
print(f"\\hypertarget{{R1b}}{{2.1}}")   # Std deviation

标签格式：{prefix}{line_number}{letter}，其中 letter = a、b、c……，用于标记同一行上的多个数值。

步骤 2：在论文正文中引用

使用 \hyperlink 在论文中创建可点击的引用：

Our method achieves \hyperlink{R1a}{45.3}\% accuracy
($\pm$\hyperlink{R1b}{2.1}).

步骤 3：对计算所得的数值使用 \num

对于由其他数值推导出的值，使用 \num{} 进行编译时计算：

% \num{formula, "explanation"} → evaluated at compile time
The improvement is \num{45.3 - 38.7, "accuracy gain"}\%.

步骤 4：生成附录代码清单

创建附录，列出完整代码，并在相关行添加 \hypertarget 锚点：

\section*{Appendix: Code Listing}
\begin{lstlisting}[escapechar=@]
@\hypertarget{code1}{}@result = model.evaluate(test_data)
@\hypertarget{code2}{}@accuracy = result['accuracy']
\end{lstlisting}

步骤 5：验证可追溯性

• 论文正文中的每个数字都必须对应代码中的一个 \hypertarget
• 每个 \num{} 公式都必须正确求值
• 点击测试：PDF 中的每个超链接都必须跳转到正确的代码行

LaTeX 设置

所需宏包：

\usepackage{hyperref}
\usepackage{listings}

规则

• 论文中的每个数值结果都必须追溯到代码输出
• 切勿手动输入数字——始终引用带标签的输出
• 对任何推导或计算所得的数值使用 \num{}
• 附录中的代码清单必须与实际执行的代码一致
• 编译后验证所有超链接都能正确跳转

相关技能

• 上游：experiment-code、data-analysis
• 下游：paper-compilation
• 另请参阅：paper-assembly