A starter kit for the economist’s first week in Claude Code

Session two starts from zero

The first-session walkthrough closes with an exercise: exit Claude Code, reopen it, and ask it to continue where we left off. It cannot. The project context we typed in, the conventions we explained, the codebook we reviewed and committed, all of it is gone. Session two starts from zero, and session three will start from zero too.

The fix points toward files. A restart wipes the conversation; it never touches the project folder. Whatever we want the second session to know has to be written down where the tool reads it, and building that scaffolding from a blank folder tends to consume the weekend we had set aside for the analysis itself. claude-code-econ-starter skips the blank folder: seven copyable files for an economist opening Claude Code on a real project, installable in about ten minutes.

The kit carries a second job as well. The walkthrough’s sharpest warning was about correctness: the tool can write code that looks right and is wrong, and verification is our responsibility. A warning is hard to act on; a routine is easy to run. Part of the kit turns that warning into a pass or fail check, and the demonstration below shows the check catching a bug that no amount of staring at output would reveal.

Ten minutes to install

Installing means copying files; there is nothing to compile and no package manager involved. Option A is a single sentence pasted into Claude Code inside the project, addressed to the tool:

Clone https://github.com/dphdame/claude-code-econ-starter into a temporary folder, copy templates/CLAUDE.md into the root of my current project as CLAUDE.md (ask me first if a CLAUDE.md already exists), copy checklist/verification-checklist.md into my project, copy each folder inside skills/ into ~/.claude/skills/, then list everything you installed and delete the temporary clone.

Option B does the same by hand from the terminal:

git clone https://github.com/dphdame/claude-code-econ-starter
cp claude-code-econ-starter/templates/CLAUDE.md ./CLAUDE.md
cp claude-code-econ-starter/checklist/verification-checklist.md .
cp -r claude-code-econ-starter/skills/* ~/.claude/skills/
rm -rf claude-code-econ-starter

Under either path, five of the seven files land in seconds: the context file, the checklist, and the three skills. They land in two different places, and the difference between the places matters. The other two, the glossary and the desk reference, come back a few paragraphs below.

The context file and the checklist go into the project folder itself. The context file is named CLAUDE.md: a plain markdown file that Claude Code reads automatically at the start of every session opened in that folder, holding data conventions, file organization, current focus, and known pitfalls. This is the direct answer to the restart exercise. The conventions we typed into session one and lost now live in a file every future session begins by reading.

The three skills go somewhere else: ~/.claude/skills/, a home-directory folder Claude Code checks for every project on the machine. A skill is a saved instruction file for a repeated task, a recipe card the tool follows the same way each time we invoke it by name, by typing /validate-estimator into the prompt, for instance. We have never used one at this point in the series, and that is fine; the setup guide covers installation and first invocation step by step.

The last two files never enter the project at all, and since both install paths delete the clone, they live on the kit’s GitHub page rather than on the machine. GLOSSARY.md defines ten week-one terms, each with one line on why it matters for research, and pairs well with the first-session walkthrough for the first hour at the keyboard. The desk reference is two printed pages, the checklist with checkboxes plus that same glossary, so the terms end up on paper anyway. It also prints straight from this site, no GitHub required: open the printable and print from the browser.

The copying takes seconds; the ten minutes go into the template’s brackets. Every placeholder asks for something we already know about the project: the canonical analysis file, the geographic identifier convention, the current specification. If we fill the brackets tonight, tomorrow’s session opens already knowing our FIPS convention; if we skip them, we type it again. Filling them for one live project is the entire setup cost.

What each file does

Each of the seven files stands alone; taking one is as supported as taking all seven. Take only the checklist and it covers its cost the first time a check fails.

The practices in the kit have a long lineage: standard software engineering plus the simulation checks econometrics has run for decades, with the design rationale for each file in the articles linked in the table above. For a lecture-length walkthrough of this territory aimed at economists, Paul Goldsmith-Pinkham’s Claude Code for empirical research series (Markus Academy) works through it across eight episodes, and the lectures are worth watching alongside the setup.

One glossary entry deserves a preview, because it names the force behind this whole article. The first-session walkthrough mentioned that long sessions eventually fill the context window, the bounded amount of text the model considers at once. When the window nears its limit, the session gets summarized automatically; that summarizing is called compaction, and it is the moment unwritten decisions vanish even inside a single long session. If we write a decision into a file before the window fills, it survives compaction; if it stays in the conversation, it may not survive the summary. The budgeting logic for treating the window as a scarce resource is worked out in the context-window article.

The seven files split into infrastructure and seed. The template’s sections, the checklist’s thirteen checks, and the verify_estimator function below are shipped infrastructure, designed to be lifted whole. The three skills and ten glossary terms are a starter seed, and the first-skill-template skill is the mechanism for growing it: the skills we eventually write for our own projects (robustness batteries, table formatting, referee-memo prep) are what keep saving time on each next project.

How much of it is tested

The kit is at v0.1, so the tested surface is narrow enough to state exactly. Both install paths run end to end; the three skills install and answer when invoked by name under Claude Code v2.1.205, the version recorded at the top of the kit’s README; and the planted-truth demonstration below ran with a frozen seed, so every number in this article reruns identically from the saved script.

Breadth is what remains untested. Three skills, a ten-term glossary, and a template whose examples assume a Python or R workflow, with no Stata-specific conventions yet. The conventions encoded reflect one applied microeconomist’s projects. If our work is applied micro in Python or R, the template fits as shipped; a structural or macro workflow rewrites parts of it before trusting it.

Watching the check catch a bug

An estimator implementation runs without error and prints a coefficient in a plausible range. What have we learned about whether it estimates the right quantity? Nothing; a clean run carries no signal either way. The validate-estimator skill packages the oldest answer simulation econometrics has to that problem: test the code on data built around a truth we already know. The instrument for that is a data generating process, a DGP: a small program that manufactures fake data where we chose the true effect ourselves, so we know what the right answer is. An implementation that cannot recover an effect we planted has no business estimating an effect we are trying to discover.

The skill carries a small generic tool, copied here verbatim from the skill file:

def verify_estimator(estimator, simulate_dgp, true_effect, tol, reps=1000, seed=0):
    """Plant a known effect, run the estimator across many draws, and check
    whether the mean recovers the truth. Catches biasing bugs; it does NOT
    validate identification, and it misses bugs that leave the estimate
    unbiased (see the limits section)."""
    draws = np.array([
        estimator(simulate_dgp(true_effect, np.random.default_rng(seed + i)))
        for i in range(reps)
    ])
    bias = draws.mean() - true_effect
    return {"mean": float(draws.mean()), "bias": float(bias), "passed": bool(abs(bias) <= tol)}

In plain terms: the function manufactures 1,000 fake datasets (each one is a draw), runs the estimator on every draw, and averages the 1,000 estimates. An average within ±0.05 of the planted effect passes; anything further fails. The seed of 0 pins the random numbers, so the whole exercise reruns identically on any machine.

To exercise the tool we plant a truth inside a staggered-adoption difference-in-differences, the kind of design many of us estimate every week. Cohort A is 30 counties adopting at period 3 of a nine-period panel indexed 0 through 8, so treatment covers periods 3 through 8 and each county contributes 6 treated periods: 30 × 6 = 180 treated county-by-period observations, which we will call cells, each receiving a per-cell effect of 2.0. Cohort B is 120 counties adopting at period 6, treated in periods 6 through 8 for 3 treated periods each: 120 × 3 = 360 cells at a per-cell effect of 0.5. One hundred never-treated counties serve as controls. The planted average effect is the cell-weighted mean across all treated cells, and the arithmetic is worth writing out in full:

(180 × 2.0 + 360 × 0.5) / (180 + 360) = (360 + 180) / 540 = 540 / 540 = 1.00.

The setup is lopsided on purpose: unequal cohort sizes, unbalanced timing, heterogeneous effects. Built lopsided, the fake data gives a dropped weight somewhere to show; built balanced, the bug below sails straight through, and the limits section shows exactly that.

Two implementations of the aggregation step go through the tool. Both compute the same two cohort-level estimates, e_a and e_b, from identical first lines. They differ in exactly one line, the return. The correct line combines the cohort estimates with treated-cell weights:

return (e_a * CELLS_A + e_b * CELLS_B) / (CELLS_A + CELLS_B)

The buggy line takes a plain average of the two cohort estimates, as if 30 counties and 120 counties deserved equal say:

return (e_a + e_b) / 2.0

The substitution is an easy one for an AI assistant to make, because everything imports and runs cleanly either way. Here is what the check reports for each:

The single-draw column is the number one clean run prints, the number a memo would quote. The mean over 1,000 draws is what the check judges, and 1.2487 sits far outside ±0.05 of the planted 1.00.

If we trust the clean run, the memo goes out reporting 1.24 where the true effect is 1.00, overstating the program by roughly a quarter; an agency scaling the program into the later-adopting counties, where the true per-cell effect is 0.5, budgets against returns the data do not contain. If we run the check first, the 1.24 never leaves the building. On the kit’s checklist this is items 8 and 9 doing their work: item 8 requires the planted value to be recovered within a stated tolerance, and item 9 requires the simulated data to break the easy symmetries so a dropped weight shows up as a detectable difference.

What the check cannot catch

Rerun the same buggy estimator on symmetric data, with equal treated-cell counts and one common effect across cohorts, and the check returns 1.0001 and passes. The bug is still sitting in the code; a plain mean and a weighted mean coincide exactly when the cells balance, so on balanced fake data there is nothing for the check to see. That is why item 9 exists, and the lesson generalizes: the routine is only as strong as the planted process, and a bug the process never exercises goes undetected.

Two further classes escape entirely. Bugs that leave the estimate unbiased never move the mean across draws, so no tolerance can flag them. An error that scrambles the order observations are processed in is one example: each draw’s estimate wobbles, but with no push in either direction, so the average across 1,000 draws sits exactly where it did. The skill routes those to checklist item 10, the line-by-line reading of the implementation against the source, where some errors appear only in the reading and never in any simulation output. Identification is the last class, and the largest: recovering a planted value validates the implementation, never the design. Whether parallel trends is credible in the real data stays a human judgment the tool cannot render, exactly the division of labor the first-session walkthrough drew. The routine work moves to files; the judgment about what the estimate means stays with us.

Next steps

A reasonable second session copies the kit in through either install path, fills the template’s brackets for one live project, and prints the desk reference; GLOSSARY.md next to the keyboard covers most of the vocabulary the next few sessions will surface. Readers following the AI for Applied Researchers sequence will find this kit running underneath all five steps; if we set it up before step one, every later step inherits it.

The practices in these files were worked out one live project at a time across our Claude Code series: the context file in One Context File, Zero Re-Explanations, the validation habits behind 400 Labels to 94% Accuracy and 6,613 Stores, $147, Zero Lost Data. The first-session walkthrough pairs with GLOSSARY.md for the first hour at the keyboard. The natural second week is a first custom skill: /first-skill-template turns whichever task we keep re-explaining into a saved file with explicit steps and success criteria, and from that point the kit’s seed skills recede behind the ones we write for the project at hand.

Worth taking with us

A convention belongs in CLAUDE.md once we have explained it to the tool in three consecutive sessions; that is the template’s own test, worth adopting whole. A clean run is where trust starts, never where it ends; skip the checklist and the 1.2487 above is the price. Planting a known truth converts “does this coefficient look plausible?” into a pass or fail, and breaking the symmetries in the simulated data is what makes a pass mean something; the check still cannot detect unbiased bugs or identification problems, so the line-by-line reading and the design judgment stay with us. Session capture costs about five minutes and spares the next morning’s reconstruction, because neither a restart nor compaction preserves the reasons a decision was made.

Have input? Get in touch.

---