技巧精选

Garry Tan 分享 methodology-appendix 技能:让同事的 Agent 能复现你的分析报告

精选理由

Garry Tan 公开了他团队用的一个 Claude Skill,给每份数据报告自动加复现附录。写分析报告的人应该抄走这份提示词:改字段口径时结论会不会变、怎么重建 PDF 都写清楚,同事的 Agent 拿到就能跑通,不用再追问细节。

Y Combinator 的 Garry Tan 分享了一个名为 methodology-appendix 的 Claude Skill,用于解决团队间 Agent 分析结果无法复现的问题。核心规则是:任何基于数据查询的报告、PDF 或页面,末尾必须自动附带一份复现附录,无需人工确认。

正文

这份附录包含六个部分:头部信息(所需工具与数据快照日期)、信号定义(说明选了哪个字段、排除了哪些备选及对结论的影响)、逐字查询语句、带命名常量的推导伪代码、重建命令、以及数据漂移与局限。检验标准是:拿到同等数据权限的读者,仅凭附录就能用 Agent 从头重建整份文档,不需要联系作者。

文内还规定正文只陈述结论,首句即给出发现,过程叙述一律移到附录。Tan 称他和同事都频繁互发 PDF 和 markdown 文件并用各自的 Agent 解读,这套方法论让不同 Agent 之间的分析结果可以互相校验与复制。

原文 · Garry Tan

I send around PDFs and markdown files to my coworkers so much and they use their agents to make sense of the world too, so I started using this skill methodology-appendix to make sure their agents could replicate what my agents found.

--- name: methodology-appendix description: "Every data-backed report or memo ends with a Methodology / Replication Appendix: the signal choice and its sensitivity, verbatim queries, derivation pseudocode over named constants, the rebuild command, and drift/limits. Appended by default, without asking." ---

# Methodology / Replication Appendix

## Rule

Any report, PDF or page whose conclusions rest on data queries ends with a **Replication Appendix**. It is a working recipe, not a citation list. The test:

> A reader with an agent and equivalent data access can regenerate the document > end to end from the appendix alone, without contacting the author.

If a reader would have to ask "which column did you use?", "what date was this pulled?" or "how do I rebuild the PDF?", the appendix failed.

## Body voice

The body states conclusions plainly. No process narration ("I was asked...", "on the first pass..."), no self-grading. The first sentence after the title contains a finding. Everything about how you got there goes in the appendix at the end, written for forensic recreation.

## When this fires

Always, automatically, for: - analysis memos backed by database or API queries - any PDF sent to partners, executives or external stakeholders - pages presenting quantitative findings - anything with tables of counts, rates or percentiles

Skip for narrative or qualitative writing, meeting notes, personal memos, short ephemera, and documents with no data spine. Do not ask permission.

## The six sections

### 1. Header

```markdown ## Replication Appendix

A reader with an agent and equivalent data access can regenerate every number and rebuild this document from this appendix alone.

**Access required:** <tool/CLI + auth, internal APIs> **Snapshot date:** <ISO date>. Live-data documents won't reproduce exactly after this date; see Drift. ```

### 2. Signal definitions and the choice that mattered

The most important section. Analyses usually turn on one column or threshold choice. Name it, name the alternatives, state the impact.

```markdown ### Signal definitions

| Field | What it is | Why chosen / rejected | |---|---|---| | `score_a` | Ensembled score | **Primary.** More predictive per <source>. | | `score_b` | Single-model score | Rejected as primary; kept for contrast. | | final_decision | Human decision object | Not queried. Known gap. |

**Outcome sensitivity:** switching from score_b to score_a moved the headline count from N1 to N2 and changed claim X. A replication that changes the signal column will not match these numbers. ```

Always include an **Outcome sensitivity** line. If a different defensible choice changes the conclusion, the reader must know before quoting it.

### 3. Verbatim queries

Every query that produced a number, copy-pasteable, in document order, labelled by the finding it supports. Never paraphrase SQL. Never write "similar to the above." Add schema notes a replicator would otherwise get wrong: enum meanings, non-obvious joins, columns that seem to exist but don't.

### 4. Derivation pseudocode

Queries give raw counts; the document has derived figures. Show the arithmetic, with assumptions as named constants a reader can swap.

``` ITEMS_PER_DAY = 8 # observed median, <period> YIELD_HAIRCUT = 0.10..0.15 # marginal cases convert below observed rate

gap = count(status = REJECTED and score >= threshold) extra_days = gap / ITEMS_PER_DAY added_wins = gap * YIELD_HAIRCUT ```

Different constants change the recommendation, not just the number, so they must be visible.

### 5. Rebuild command

Exact commands from source markdown to verified PDF, plus a visual check (e.g. `pdfinfo` page count, `pdftoppm` a couple of pages and look at them). Name the source of record: the PDF is a render, never the original.

### 6. Drift, limits and known gaps

- **Live data moves.** What was mid-flight at snapshot; what is closed and stable. - **Coverage gaps.** Fields only populated for part of the range, and how tables were restricted rather than shown with misleading denominators. - **What this cannot see.** Inputs to the real decision that the data lacks. - **Retractions.** Any claim withdrawn between versions, and why.

## Procedure

1. Log queries verbatim as you run them. Reconstructed SQL is how appendices go wrong. 2. Write the analysis. 3. Append the six sections before rendering. 4. Name the signal choice and its outcome sensitivity. 5. Render, check visually, then send. 6. On revision, update the appendix in the same commit as the finding. An appendix describing a superseded method is worse than none.

## Quality bar

- [ ] Could a reader re-run this without asking me anything? - [ ] Is every headline number traceable to a pasted query? - [ ] Is the signal/threshold choice named, with alternatives and impact? - [ ] Are derived figures arithmetic over named constants? - [ ] Is the rebuild command present and correct? - [ ] Are drift, coverage gaps and retractions stated?

## Anti-patterns

- **Citation theater:** table names instead of runnable queries. - **Reconstructed SQL:** retyped from memory, drifted from what ran. - **Silent signal choice:** one column presented as "the score" when a defensible alternative changes the answer. - **Buried assumptions:** constants hard-coded in prose. - **Stale appendix:** findings revised, appendix untouched. - **Asking first:** this is a default, not an offer.

产业坐标与信源核验

本条情报归属 AITOP「技巧」核心栏目,重点聚焦北美前沿实验室与硅谷科技巨头。在跨区域产业观察坐标中,该动态直接关联「AI 开发者工具链、Coding Agent 与工程化实践」研究主线,反映出当前技术演进与商业落地的最新风向。涉及核心实体与技术议题包括:Claude、提示词工程、Claude Skills、数据分析,读者可通过下方标签进入对应专题页查阅历史脉络与关联对比。

信源核验说明:本文原始线索采编自「Garry Tan」(@garrytan),经 AITOP 多维评分管线结构化提炼。