Website of Peter Westerman

When you work with a human colleague on a long-running project, context accumulates passively. They remember last week’s decisions, they understand your conventions, they know which approaches have been tried and found lacking. You do not re-explain your project history at the start of every meeting because they were there for the history. The shared context that developed over months of collaboration makes every conversation more efficient than the first one.

AI systems do not work this way. Every session starts from zero. The AI retains nothing from previous sessions unless you provide it explicitly. Every new conversation begins with a system that knows nothing specific about your project, your preferences, your decisions, or your history — unless that information is loaded as context at the start of the session. The implicit shared context that powers efficient human collaboration does not exist.

This characteristic is well-known in principle. What is less well-understood is the cumulative cost of failing to systematically address it — the cost of context debt. Context debt accumulates when context infrastructure is not built and maintained, and it is paid back in time and tokens in every session where re-establishment happens instead of productive work.

What the Re-Establishment Overhead Looks Like

In the early months of the practice documented in this case study — before context files were well-maintained, before the Playbook existed, before the Agent System established session protocols — a typical session opening looked something like this:

“I’m working on a WordPress plugin called AI News Cafe. It’s a content aggregation plugin that pulls articles from multiple RSS feeds, generates AI summaries using Claude, and provides an editorial workflow. The main plugin file is at ai-news-cafe.php in the root. We’ve been using a singleton pattern for the main plugin class. The Claude API key is stored in a WordPress option called ai_news_cafe_claude_api_key. The database has two tables: wp_ainc_articles for storing articles and wp_ainc_queue for the editorial queue. The admin panel is registered at admin-page.php using the add_menu_page WordPress hook. Last session we completed the article ingestion system. Today I want to work on the editorial queue…”

That opening paragraph adds zero new information to the project. It is pure re-establishment of context that was established in previous sessions and should have been maintained in a context file. It consumes tokens and time. And it happens at the start of every session, because without it the AI will make decisions that conflict with the existing architecture — treating the existing code as if it did not exist.

Rough estimate of the cost: across several hundred sessions over twelve months, if fifteen percent of each session’s tokens were consumed by context re-establishment at an average of seventy-five thousand total tokens per session, that represents about eleven thousand tokens per session consumed by orientation rather than production. At current AI API pricing, across three hundred sessions, the cumulative cost of context debt is measurable in thousands of dollars. More importantly, it is measurable in hours of time that could have been productive but was spent on reconstruction.

The Context File Solution

The solution is simple and the investment is small. Every project gets a context file — named CLAUDE.md in this practice — that lives in the project directory and is loaded at the start of every AI session. It contains everything the AI needs to begin working productively without any re-orientation:

Project purpose and scope in two to three sentences. Technology stack: language, framework, external services, key libraries. Architectural decisions and the reasoning behind them. Coding conventions: class naming, file organization, error handling patterns. Current database structure. The current state of the build — what is complete, what is in progress, what is next. Constraints discovered since the last update. Things not to do in this codebase.

With a well-maintained context file, the session opening becomes: “Today I want to build the editorial queue feature — specifically, the queue listing view with status filters and the individual review workflow.” Full stop. The AI reads the context file and has everything it needs to begin. The first response is production work. The fifteen-to-twenty-minute re-establishment overhead is gone entirely.

The investment: thirty minutes to build the initial version, five minutes at the end of each session to update it with decisions made during that session. The return: fifteen to twenty minutes recovered at the start of every subsequent session, plus improved first-pass output quality because the AI is working from accurate current context rather than inferred context. Over a hundred sessions on a single project, that compounds into significant recovered time and measurably better output.

The Playbook Layer

Context files solve the per-project context problem. The Personalized Coding Playbook solves the cross-project context problem — the fact that, without documentation, each new project starts from the same baseline regardless of what was learned in previous projects.

By the twelfth product, there was an enormous amount of accumulated learning: which patterns worked, what the conventions were, how to handle recurring technical problems, what the standard approach for each type of component was. Without the Playbook, that learning lived in chat transcripts and personal memory — inaccessible to AI sessions on new products unless explicitly restated. With the Playbook, AI sessions on new products immediately benefited from the patterns established in all previous products.

The Playbook version distinction matters: V1 was useful but organized for human reading, not AI reference. V2 was reorganized specifically for how AI systems use reference material — conventions before explanations, code examples before prose, cross-references to existing implementations. The measurable difference in session quality between V1 and V2 was immediately apparent: first-pass output using V2 deviated less from established conventions than the same session using V1, because the conventions were more accessible and clearly stated.

The Non-Software Equivalent

The context debt problem is not unique to software. Any AI collaboration on an ongoing project accumulates it if context infrastructure is not built and maintained.

Consider a professional using AI to support a quarterly market analysis report. Without a context document, every session begins with re-explaining the report’s purpose, methodology, audience, standard sections, data sources, required metrics, and tone. That re-explanation happens every quarter, every session. With a context document updated after each session, the AI starts each session with accurate current context about the project’s purpose, what has been covered, what remains, and what conventions to follow. The re-establishment overhead disappears. The sessions are faster and the output is better calibrated.

The general principle: any AI work that runs across multiple sessions on the same project or task type benefits from a maintained context document. One-off tasks do not need it. Ongoing projects always benefit from it. The discipline to build and maintain that document — immediately, from the first session, and consistently thereafter — is the single highest-return practice available in any AI collaboration workflow.

The Agent System as Advanced Context Architecture

The most sophisticated context solution developed in this practice was the Agent System — a set of specialist AI agents, each with a defined role and pre-loaded specialist context that does not change session to session. Rather than one general AI session handling everything, tasks are routed to agents whose context is already calibrated for that task type.

The QA Agent has stable context about testing strategies, common failure modes, and debugging approaches. It does not need any of that context re-established for a debugging session — it was loaded when the agent was created and is current because the agent profile is maintained when patterns change. The Architecture Agent has stable context about architectural patterns, technology stack decisions, and the trade-offs that have been resolved in this portfolio. Sessions with specialist agents are immediately expert-level rather than starting from general context.

For any professional who does significant recurring AI work in a specific domain, specialist context profiles are the equivalent. A campaign brief profile for a marketer. A financial model profile for an analyst. A research synthesis profile for a consultant. Each profile is built once, maintained as the relevant context evolves, and loaded for every session of that task type. The investment is a few hours per profile. The return runs across every future session of that type for the life of the practice.

Measuring the Improvement

The improvement from context file implementation was visible and measurable in two ways. First, session startup time: sessions that began with a current, accurate context file moved to productive work immediately. Sessions that required re-establishment took fifteen to twenty minutes before any real work was done. Over a hundred sessions on a given project, the fifteen-to-twenty-minute re-establishment overhead compounds into twenty-five to thirty-three hours of recovered time from context file maintenance alone.

Second, first-pass output quality: sessions that started from accurate context produced implementations that deviated less from established conventions on the first pass. The AI was working with correct information about what existed, what conventions were in use, and what constraints applied. When an AI session produces an implementation that needs to be corrected for convention violations or constraint mismatches, that correction overhead accumulates. Eliminating most of it through good context maintenance is a quality improvement, not just a time improvement.

The combination of saved re-establishment time and reduced correction overhead from the first context file implementation, across the ten products that directly benefited from it, is estimated at forty to sixty hours of recovered productive time. That is a real return on the ten to fifteen hours invested in building and maintaining context files across those ten products.

What Good Context Hygiene Looks Like in Practice

The specific discipline that produces the most impact: treating the context file update as part of the session, not as an afterthought after the session. The last five minutes of every session should be the context update — not as optional cleanup, but as the closing step of the session that enables the next session to be productive.

What goes in the update: the architectural decisions made in this session (one sentence each). The new constraints identified. The components added or modified. The current v1 status — what is complete, what is in progress. Any “do not do” items discovered from testing. The upcoming session’s objective, if it is clear.

The context file that is updated consistently after every session is, by session thirty, a comprehensive and accurate description of the project’s current state. The context file that is “maintained when there is time” is an increasingly stale, increasingly unreliable document that produces increasingly incorrect inferences by the AI sessions that reference it. The five-minute discipline is not optional if you want the context file’s value to hold over time.

How Recent AI Innovations Change This Picture

Context debt — the accumulated cost of AI sessions that operate with incomplete or stale context — was one of the most expensive problems in the original methodology. Recent AI innovations address it from multiple angles simultaneously, making it significantly more manageable going forward.

The 1-million-token context window is the most direct improvement. The primary driver of context debt was the hard limit on how much context could fit in a session, which forced tradeoffs: what to include and what to leave out. A 1-million-token window does not eliminate these tradeoffs — even 1 million tokens has a limit — but it pushes the tradeoff point far enough out that the entire shared library, the active product architecture, and substantial session history can coexist in a single context without crowding each other out. The strategic pruning work described in this post remains relevant at the edges, but it is no longer a session-by-session constraint on every project.

Extended prompt caching, introduced in 2025, maintains context across sessions for up to 60 minutes. For the specific problem of session restart overhead — where each new session required re-establishing the full project context from scratch — extended caching reduces the cost of short breaks in a work session. The context loaded in the morning session can still be live 45 minutes into a coffee break, without needing to be re-established.

Agent Skills address the repeatability side of context debt. Instead of manually loading the right context files at the start of each session — with the risk of forgetting something or using a stale version — Skills are version-controlled, automatically loaded resources that ensure the AI starts every session with the correct, current context for that project. Context debt from inconsistent session setup is structurally prevented rather than managed after the fact.