One Context File: A Workflow for Persistent Project Context

A new coding session often begins by re-establishing project conventions. Census tracts might be 11-digit FIPS codes stored as strings, coordinates might use WGS84, and a validated input might live at a specific path.

The article estimates that this re-explanation can take 3 to 5 minutes per session and 4.5 to 7.5 hours across a three-month project with daily coding sessions. No session log is public, so these are planning estimates rather than measured results.

Some agent-based tools can load a persistent context file at the start of a session. With Claude Code, a CLAUDE.md file in the project root can supply that context. The practical idea is to document conventions once and make them available when the tool begins work.

The Re-Explanation Tax

Let's consider a typical debugging session. A transit time calculation script crashes with a coordinate reference system error. With traditional AI assistance, we explain:

• Census tract centroids use EPSG:4326 (WGS84)
• Store locations also use EPSG:4326
• The OpenRouteService API expects coordinates in this format
• Previous scripts already validated both datasets use this system

The AI suggests a fix. We run it. It crashes again: the fix assumed FIPS codes were integers when they're actually strings. We explain this detail. The AI suggests another fix.

Each session requires re-establishing these conventions from scratch. The AI has no memory of yesterday's session where we debugged a similar issue.

What Goes in CLAUDE.md

A research project context file typically contains four types of information:

Data Conventions

## Data Conventions
- Census tracts: 11-digit FIPS codes as strings (e.g., "06085511100")
- Coordinates: WGS84 (EPSG:4326), decimal degrees
- Validated stores: data/processed/stores_validated.csv (4,847 rows)
- Transit times: minutes as integers
- Missing values: -999 (not NaN, for compatibility with older scripts)

These conventions prevent a specific class of errors. If the agent assumes FIPS codes are integers, it might drop leading zeros. If it assumes coordinates need projection, it might transform them incorrectly. If it treats -999 as a valid transit time rather than a missing value indicator, calculations break.

File Naming Patterns

## File Organization
- Raw data: data/raw/ (never modify)
- Processed data: data/processed/ (intermediate outputs)
- Final outputs: data/output/ (results for publication)
- Scripts: numbered by execution order (01_, 10_, 20_...)

When we say "the store validation file," the agent knows we mean data/processed/stores_validated.csv. When we say "the transit calculation script," it knows to look for scripts/30_calculate_transit.py.

Current Analysis Focus

## Current Work
Analyzing relationship between transit-based grocery access and SNAP enrollment.
Key hypothesis: geographic access (store proximity) matters less than economic access (SNAP rates).
Current script: scripts/40_calculate_vulnerability.py
Known issue: Vulnerability calculation needs refinement for rural tracts.

This context helps the agent understand why we're asking certain questions. If we say "the vulnerability calculation seems wrong," it knows we mean line 47 in scripts/40_calculate_vulnerability.py, and it knows the current concern is how rural tracts are handled.

Known Pitfalls

## Known Issues & Edge Cases
- Rural tracts: Some have zero grocery stores within 60 minutes by transit
  Handle these as NA rather than setting to maximum time
- Coordinate precision: Round to 6 decimal places (sufficient for ~10cm accuracy)
- API rate limits: OpenRouteService allows 40 requests/minute
- Data vintage: Census 2020 geometries, ACS 2023 5-year estimates (mismatch acceptable)

We discovered these issues through previous debugging sessions. Without documentation, we'd rediscover them every few weeks as we encounter edge cases again.

Reconstructed Illustration: Before and After

The following dialogue is an illustrative scenario, not a transcript or independently timed benchmark. The exact times are retained as article-reported estimates so the comparison remains transparent.

Before CLAUDE.md

Session 1 (Monday):
"Fix the transit calculation error."
"What format are your coordinates in?"
"WGS84."
"What format are FIPS codes?"
"Strings with leading zeros."
Time to first working fix: 12 minutes.

Session 2 (Tuesday):
"Optimize the vulnerability score calculation."
"What format are your coordinates in?"
"WGS84."
"What format are FIPS codes?"
"Strings."
Time to first working fix: 15 minutes (we forgot to mention leading zeros).

Session 3 (Wednesday):
"Generate maps of vulnerability scores."
"What coordinate system should I use?"
"WGS84."
Time to first working fix: 8 minutes.

Article-reported cumulative time in this illustration: 35 minutes over three sessions.

After CLAUDE.md

Session 1 (Monday):
"Fix the transit calculation error."
Agent reads CLAUDE.md, sees coordinate system and FIPS format
"Found the issue: line 47 treats FIPS codes as integers, dropping leading zeros."
Time to first working fix: 3 minutes.

Session 2 (Tuesday):
"Optimize the vulnerability score calculation."
Agent reads CLAUDE.md, sees data conventions and current analysis focus
"Reviewing scripts/40_calculate_vulnerability.py. Should I maintain the rural tract NA handling mentioned in Known Issues?"
Time to first working fix: 4 minutes.

Session 3 (Wednesday):
"Generate maps of vulnerability scores."
Agent reads CLAUDE.md, sees coordinate system and output conventions
"Creating map with WGS84 coordinates, saving to data/output/figures/ per file organization pattern."
Time to first working fix: 2 minutes.

The illustration assigns zero minutes to re-explanation after the context file is added. That value was not independently measured.

Error Prevention

A well-maintained CLAUDE.md file can reduce errors caused by undocumented conventions. Consider coordinate reference systems.

Without context: An agent might assume coordinates need projection for distance calculations. It projects WGS84 to Web Mercator (EPSG:3857). Transit times now use Euclidean distance in meters instead of the original great circle distances in the API data. Results are subtly wrong. We don't notice until comparing results to manual spot-checks days later.

With context: The CLAUDE.md file states that coordinates are WGS84 and should remain unprojected. This gives the agent a reason to preserve that convention and makes the assumption easier to catch before execution.

The same pattern can help with FIPS codes, missing-value conventions, and file locations. A context file is a guardrail, not proof that an error cannot occur. Tests and review are still required.

Time Savings

The article reports the following estimates for a food security project. They are not backed here by public timing logs:

The article also reports the following project outcomes. No public issue log or session record independently validates the zero counts:

• Article-reported zero coordinate-system errors after adding CLAUDE.md
• Article-reported zero FIPS leading-zero errors
• Article-reported zero incorrect file-modification incidents, such as overwriting raw data

The article estimates that debugging these errors takes 15 to 30 minutes each and that the context file may have prevented 8 to 10 incidents, for another 2 to 3 hours. These are retrospective estimates, not observed counterfactuals.

Article-reported total savings: approximately 6 to 7 hours across the project. Treat this as a hypothesis to measure in future work, not a verified benchmark.

What Not to Include

CLAUDE.md documents conventions, not code. We don't put:

• Entire data processing pipelines (those belong in scripts)
• Statistical methods in detail (those belong in README or papers)
• Every variable definition (code should be self-documenting)

The file contains information that would otherwise live in our heads: the unwritten conventions we apply when writing code.

If we catch ourselves explaining the same thing to AI in three consecutive sessions, that explanation belongs in CLAUDE.md.

Maintenance

The context file evolves with the project. When we discover a new pitfall (rural tracts need special handling), we add it. When we change conventions (switching from NaN to -999 for missing values), we update it.

The article estimates maintenance at approximately 2 minutes per week. The practical payoff is less repeated setup, but the amount should be measured with session logs rather than assumed to be zero.

We update CLAUDE.md in three situations:

1. After discovering an edge case through debugging
2. When changing project conventions
3. When starting a new analysis phase (update "Current Work" section)

Implementation

The article estimates that creating a CLAUDE.md file takes 15 to 20 minutes. A useful first pass documents:

1. Data formats and conventions (5 minutes)
2. File organization patterns (3 minutes)
3. Current analysis focus (2 minutes)
4. Known pitfalls we've already discovered (5 minutes)

The article estimates that this initial investment can save more than 4 hours over a three-month project. No public session log independently times that comparison.

The article describes a 47-line CLAUDE.md file for the food security analysis. The file itself is not linked here, so the line count and its project history are article-reported rather than publicly reproduced.

The decision rule is simple: compare the cost of maintaining concise project context with the measured time spent repeating conventions and correcting context-related errors.

Next in series: Methods-to-Code with AI: An Article-Reported Workflow explores how well-specified methodology sections become direct implementation guides.