What is AI memory, and why is it not the same as a larger context window? This guide explains four types of memory and the four jobs every memory system performs; examines Generative Agents, MemGPT, Voyager, MemoryBank, and HippoRAG; compares ChatGPT, Claude, and Mem0; and tackles the two hardest questions: what to remember and what to forget.

Large language models have an easily overlooked property: they have no memory by default. Each call starts from a blank slate. The model remembers neither what you just said nor what you discussed last time unless that information is placed into the context window again. When ChatGPT seems to "remember me," that is not an intrinsic model capability; an external memory system is storing and retrieving information on its behalf.

This article explains what that system contains, how it works, and how real products implement it. It is a sequel of sorts to the context engineering article: if context engineering decides what belongs in the window for this step, memory decides what is worth preserving across time and when it should be recalled.

1. First clarify: memory ≠ larger context window

This is the most common misconception. Many people assume that expanding a context window from 8K to 1M tokens solves memory. It does not.

context window is the workbench, and the memory is the warehouse. There are three differences:

• Persistence: context window is volatile and will be cleared at the end of a conversation; the memory must exist across sessions, days, and months.
• Capacity: No matter how large the window is, there is an upper limit, and the more crowded it becomes, the lower the signal-to-noise ratio, the worse the effect (context rot, see "context engineering"); the warehouse is theoretically unlimited.
• Cost: Every token in the window must be recalculated and recharged at every step; the information in the warehouse lies quietly, and only a small part is taken into the window when needed.

Therefore, the core task of a memory system is not to keep all history in the window, but the opposite: move information outside the window, then retrieve the right small piece at the right time. In one sentence:

Memory trades abundant storage outside the window for scarce attention inside it.

This is why an "infinitely long context" cannot replace memory: even if a window could hold a year of conversations, a model would struggle to use all of it effectively, and the cost would be enormous. A warehouse and a workbench serve different purposes.

2. The map given by the human brain: several types of memory

The classification of AI memory almost copies the division of human memory by cognitive science. Remember this picture, and all subsequent architectures will fall into place.

short-term memory (Short-term / Working Memory): The "working memory" used for the current task is equivalent to the computer's RAM. In LLM, it is basically equal to current context window - the ongoing conversation and the return of the tool just obtained. Volatile, limited capacity, fast.

long-term memory (Long-term Memory): Information retained across sessions, equivalent to a hard disk. It is further divided into three types. This distinction is very important:

A useful judgment method: episodic memory answers "what happened", semantic memory answers "what is true", procedural memory answers "what to do". The most solid one for most products today is semantic memory (remember your preferences and facts), followed by episodic memory, and procedural memory is the most difficult and cutting-edge - it means that Agent can "learn a set of practices" from experience and solidify them.

3. Four things a memory system really does

Fancy nouns aside, any memory system does four things in a loop. These four verbs are the backbone of your evaluation of any solution:

1) Writing/Encoding - From this interaction, determine "what is worth remembering" and organize it into a storable memory. The difficulty is choose: remembering everything will pollute the future, missing memory will cause amnesia.

2) Storage - put memory into a carrier outside the window: database, vector library, knowledge graph or pure file. This step determines how to search later.

3) Retrieve - During the next interaction, determine "which items should be remembered this time" and enter them into context window. If you take too much, it will be noise; if you take too little, it will be insufficient.

4) Update/Forget - Memories will become outdated and conflict ("He lived in Shanghai last year and moved to Beijing this year"). The system must be able to correct old memories and eliminate useless memories instead of mindless accumulation.

If you read the article "context engineering", you will find that this is exactly the expansion of the two operations "Write" and "Select" in the time dimension - write = Write, retrieve = Select. Memory is not a new thing, but a branch that grows along the "time axis".

To judge whether a memory system is good or not, don't look at "how much it can store", but whether it does these four steps accurately - especially the Writing trade-off and the Forgetting update, these two steps are the most difficult and can widen the gap the most.

4. Several classic architectures that you must know

There is more than one classic design for memory. The following five are the skeletons for understanding all memory systems. Each one pegs a different key ability. After reading this, you will have a complete "capability map".

1. Generative Agents: memory stream + Reflection

In 2023, Stanford's famous "Generative Agents" (allowing 25 AI villains to live independently in a virtual town) explained the memory architecture clearly for the first time, and it is still a must-read for beginners. It consists of three parts:

• memory stream (Memory Stream): A continuously appended list of experiences recorded in natural language. Everything the villain sees, hears, says, and does is written down in chronological order.
• Retrieval: It is impossible to fit the entire stream into the window, so each time score selection is based on the current situation - the score is a weighted sum of three dimensions: relevance (semantic similarity to the current situation), recency (the longer I don’t think about it, the lower the score, exponentially decaying over time), importance (the score when writing, low for "having breakfast", high for "breaking up with my lover").
• Reflection: The most important step. The Agent regularly reviews recent memories, synthesizes higher-level conclusions (summarizes "I seem to like Klaus next door" from scattered interactions), and then writes them back into the stream as new memories. Reflection upgrades memory from "running account" to "insight".

Remember these three words - memory stream, search by relevance/recency/importance, and reflect. Almost all memory systems later performed addition and subtraction on this skeleton.

2. MemGPT: Treat LLM as an operating system (layered + self-editing)

If Generative Agents gave a paradigm of "retrieval", then MemGPT in 2023 (the subtitle of the paper is called Towards LLMs as Operating Systems, now incorporated into the open source framework Letta) gave a paradigm of "hierarchical management". Its insight is wonderful: context window is like the physical memory (RAM) of the operating system, and the storage outside the window is like a disk; the operating system relies on "paging" to swap in and out to create the illusion of "infinite memory" - LLM can also do it.

The most critical design is: The model has a tool to "edit its own memory" - when the core memory is almost full, it decides which items to move to the archive and which items to transfer back to the core. This changes "memory management" from hard-written rules to the ability of the model itself. This set of "layered + self-editing" ideas has directly affected product-level implementation: For example, Anthropic added a "memory tool" to Claude in September 2025 - giving the model a dedicated file directory, allowing it to add, delete, modify and check by itself, and accumulate knowledge across sessions; combined with "context editing (automatic cleaning of expired tool calls in the window)", official data shows that 84% of tokens were reduced in 100 rounds of web search evaluations, improving compared to the baseline 39%. The same skeleton, productized look.

3. Pin a key point on each of the other three: Voyager, MemoryBank, HippoRAG

• Voyager——The skill library is "procedural memory". ** This autonomous exploration agent in "Minecraft" in 2023 allows the model to generate executable code for each new task and store the run-through programs in natural language description** into the growing "skill library"; next time it encounters a similar task, it can directly retrieve and combine old skills without thinking about it from scratch. This is exactly what the second section says - what is stored is not "facts", but "the ability to do it".
• **MemoryBank - Equip memory with a "forgetting curve". ** It brings the Ebbinghaus forgetting curve of psychology into AI: each memory has a "strength", which is strengthened when it is recalled, and decays if it is not touched for a long time. During retrieval, semantic similarity and this "retention score" are combined. It provides an elegant machine answer to the seventh section "What to forget" - it is not a one-size-fits-all deletion, but a natural forgetfulness and awakening like a human being.
• HippoRAG - map the hippocampus. It borrows the "hippocampal index theory" from neuroscience: treat LLM as the "neocortex", build another knowledge graph as the "hippocampal index", and use an algorithm similar to PageRank to associate on the graph during retrieval. It is the most theoretically ambitious line of picture memory-it is good at connecting scattered clues to answer questions.

Putting the five together is a "capability map" of memory design: Generative Agents is responsible for retrieval and reflection, MemGPT is responsible for hierarchical scheduling, Voyager is responsible for skill accumulation, MemoryBank is responsible for forgetting, and HippoRAG is responsible for association. Whichever ability you lack, just look at the design of that area.

5. What does the memory in the product look like?

Put the architecture into the products you use every day:

ChatGPT: Two layers of memory. One layer is Saved Memories - a list of explicit facts that you can view and delete ("I am a vegetarian"), and the model automatically writes in it; the other layer is Reference Chat History that will be launched in April 2025 - it does not make a list, but implicitly captures patterns from all your past conversations to make the answers more relevant to you. Both layers can be turned off individually in settings, and temporary conversations do not read or write memory. In 2026, OpenAI added a background mechanism to automatically organize memory, making the memory more and more accurate over time.

Claude: We are following the "file-based memory tool + contextual editing" route mentioned in the previous section, which is more controllable by developers - the memory is stored in your own infrastructure, and you have full control of the data.

Gemini: Google has also added memory to Gemini - it can not only remember the personal information you saved in the settings, but also selectively refer to your past conversations to personalize answers. It also supports viewing, editing and closing.

Common Product Philosophy: Memory is not a black box. Allowing users to be able to see, change, and turn things off is becoming a standard feature - because once the memory is remembered incorrectly or something should not be remembered, the collapse of experience and trust will be doubled.

6. Engineering implementation: three mainstream approaches

If you really want to build your own memory system for storage and retrieval, the industry basically has three routes (often mixed):

Route 1: Full-context/Summary The simplest: put all or a summary of the history back into the window. Simple, but it will run into context rot as it grows, which is slow and expensive. Suitable for short-cycle, lightweight scenarios.

Route 2: Vector retrieval (Vector/RAG-style) Convert each memory into a vector and store it in the vector library, and then retrieve the most relevant ones based on semantic similarity. This is currently the most mainstream approach. The open source framework Mem0 is representative: it does not save the original conversation, but uses LLM to extract key facts from the conversation and save them, and only retrieves relevant memories during retrieval. On the long-range conversation memory benchmark LOCOMO commonly used in the industry, Mem0 officially reports that its accuracy is about 26% higher than OpenAI's memory solution, latency is about 91% lower, and token costs are saved by about 90%. The core win is "only feeding a small amount of relevant history, rather than the entire history."

Route 3: Knowledge Graph (Graph) Save memory as an "entity-relationship" diagram (Zhang San - works for - a certain company). Good at handling multi-hop reasoning and relationship changes over time ("He changed jobs" only needs to change one edge). Expressive, but expensive to build and maintain.

In practice, there is no silver bullet. Mature systems often focus on vectors, supplemented by maps, and abstracts.

7. The two most difficult things: what to remember and what to forget

Storage and retrieval are engineering projects, and the real difficulty is two true or false questions:

Problem 1: What to write? Not every sentence is worth remembering. Random memorization will bring about two kinds of disasters: one is noise - writing down all irrelevant trivial matters, which will interfere with future retrieval; the other is memory poisoning - an early wrong conclusion is written into long-term memory, and then retrieved every time, making mistakes along the way, and even becoming an entry point for attacks (someone specializes in "poisoning" memories). So writing must have trade-offs, deduplication, and conflict detection.

Problem 2: What should be forgotten? Memories become outdated and contradictory. The user said "I am in graduate school" last year and graduated this year; what I liked last month is boring this month. A memory bank that only increases but never decreases will sooner or later contradict itself. A good system requires update (overwriting old ones with new memories), attenuation (natural fading out if not used for a long time), and even active forgetting (users request deletion, which is also strictly required for compliance).

In a memory system, storage is the beginner level, retrieval is competence, and forgetting is mastery. Memory that can forget remains alive; otherwise, you do not get an assistant that understands you better over time, but one that carries stale assumptions and grows increasingly stubborn.

8. Developers want to add memory: Don’t reinvent the wheel, look at these solutions first

The good news is that by 2026, "adding memory to the Agent" will no longer need to be written from scratch - a number of mature open source frameworks have encapsulated the above routes. For developers who want to get started, the mainstream options are roughly the following (all can be self-hosted):

Don’t remember the parameters when choosing a model, remember this main line: What ability do you lack most, choose a framework that focuses on that ability - if it’s fast, choose Mem0, if you want to handle timing changes like "Zhang San quits," choose Zep/Graphiti, and if you want a stateful Agent that can manage its own memory, choose Letta.

The most popular new project in 2026 is exactly the opposite answer to the seventh section of "What to remember and what to forget" - MemPalace. It was developed by "Resident Evil" heroine Milla Jovovich and engineer Ben Sigman, using Claude Code, and is open sourced by MIT. It reached more than 20,000 stars two days after its release in April 2026. It started with a complaint: "I'm tired of AI deciding what to remember for me and then throwing out the context I really need."

So MemPalace went in the opposite direction and borrowed the ancient "memory palace" mnemonic technique: save the dialogue word for word without summaries, and then use spatial metaphors to organize it into wings (by people and projects) → rooms (by themes) → drawers (for original text). During retrieval, it can be "partitioned" to search accurately, instead of fishing blindly in a large group of vectors. It uses hybrid retrieval (keyword weighting + temporal proximity), and achieved a recall@5 of 96.6% on the LongMemEval benchmark for pure retrieval. The storage backend is pluggable (default is ChromaDB, SQLite/Qdrant/pgvector is also supported) and can be connected to Claude Code, Cursor, etc.

The value of MemPalace is not only that "a female star wrote a popular open source project", but that it puts the philosophical differences in Section 7 on the table: Should AI automatically cut the memory for you, or should you keep it all and control the structure yourself? ** The former is worry-free, the latter is controllable - there is no standard answer to this, but it reminds you: ** "Let AI decide what to remember" itself is a design decision that requires your own decision.

9. Ready-to-use memory-system checklist

• Do I distinguish between short-term memory (inside the window) and long-term memory (outside the window)? Didn't you think of "a bigger window" as the answer to memory?
• In long-term memory, there are three categories: Semantics/Scenarios/Programs. Which ones do I need? What do you use to save?
• Are there any trade-offs for writing? Or just keep all the conversations mindless? Is there any duplication and conflict detection?
• Should the search be sorted based on relevance/recency/importance scores, or should all be returned to the window?
• Is there an update and forget mechanism? Will old, wrong, expired memories be corrected or eliminated?
• Can users see, modify, delete, and close their own memories (experience + compliance)?
• Is the storage selection correct? Is vector enough? Do I need map to handle relationships and timing?
• Is there any protection against memory pollution? Will the wrong conclusion be biased along the way after being written into long-term memory?
• Have you considered layering like MemGPT, or added reflection like Generative Agents, so that memory can be upgraded from a running account to an insight?

Models will get smarter and smarter, and windows will get bigger and bigger. But as long as the two "attention is limited and information will be out of date" are true, whether can remember you and think of the right things at the right time will always be a system that requires careful design, rather than an ability that is given away by the model.

References

• Packer et al., MemGPT: Towards LLMs as Operating Systems (2023; now an open source framework Letta)
• Park et al., Generative Agents: Interactive Simulacra of Human Behavior (2023, memory stream / Search / Reflection)
• Wang et al., Voyager: An Open-Ended Embodied Agent with Large Language Models (2023, Skill Library / procedural memory)
• Zhong et al., MemoryBank: Enhancing LLMs with Long-Term Memory (2023, Ebbinghaus Forgetting Curve)
• Gutiérrez et al., HippoRAG: Neurobiologically Inspired Long-Term Memory for LLMs (2024, Hippocampal Index/Graphic Memory)
• Mem0, Building Production-Ready AI Agents with Scalable Long-Term Memory (2025, LOCOMO benchmark); open source warehouse mem0ai/mem0
• Open source memory framework: Zep/Graphiti, Letta, Cognee, LangMem
• MemPalace, GitHub repository (2026, Milla Jovovich + Ben Sigman, "memory palace" style); Forbes report
• Anthropic / Claude，Managing context on the Claude Developer Platform（2025，memory tool + context editing）
• OpenAI, Memory and new controls for ChatGPT and Reference chat history (2025)
• Memory in the Age of AI Agents: A Survey (2025, review and paper list)

Context engineering determines an AI agent's ceiling by controlling what the model sees. This guide explains four core operations—write, select, compress, and isolate—along with RAG versus long context, memory, KV-cache optimization, practical patterns, and a self-checklist.

Anyone building agents eventually hits the same wall: the prompt has been tuned to exhaustion, yet the results remain unstable. The problem is often not the wording of that instruction, but what the model can see at each step. This article is about managing the model's field of view. It takes engineers and technical decision-makers from concepts to practical patterns, with a checklist you can use directly.

1. A counter-intuitive fact

Many people tune an agent like this: poor result → rewrite the prompt → still poor → add more instructions → cram in every potentially useful document, conversation, and tool description → get an even worse result.

The problem is often not whether the prompt is well written, but whether the model sees the right context at that particular step.

In 2025, the industry converged on a term for this work. Karpathy put it most plainly:

"Context engineering" is a better term than "prompt engineering." People associate prompts with short, everyday task descriptions, but in any production-grade LLM application, the real craft is filling the context window with exactly the right information for the next step.

「+1 for "context engineering" over "prompt engineering". People associate prompts with short task descriptions you'd give an LLM in your day-to-day use. When in every industrial-strength LLM app, context engineering is the delicate art and science of filling the context window with just the right information for the next step.」

Shopify CEO Tobi Lütke has expressed the same preference. "Context engineering" more accurately describes the core skill: "the art of providing all the context for the task to be plausibly solvable by the LLM."

One sentence to distinguish:

prompt engineering: Write a relatively static instruction. context engineering: In a multi-step, ever-changing Agent loop, dynamically decide what to put and what not to put into the limited context window at each step.

Prompt engineering is a subset of context engineering. Once a task grows from a single question and answer into dozens of autonomous steps, tool calls, and results, the main challenge shifts from writing one instruction to managing the entire window.

2. Why context is a scarce resource

Intuitively, the bigger the context window, the better, and 1M token sounds like it can fit anything. But in practice, context is the scarcest resource for three reasons:

1) Attention is limited, and models can "forget the middle." The classic Lost in the Middle study found that models often overlook key information placed midway through a long context: they attend more strongly to the beginning and end than to the middle. Later, Chroma and others used more systematic experiments to describe context rot: performance on the same task declines steadily as context grows, even when needle-in-a-haystack tests suggest the model can still retrieve the fact. Finding information is not the same as using it well.

2) Irrelevant information will actively interfere. Every extraneous piece of content in the context is competing for attention with the correct answer. Three common symptoms:

• Distraction: Being biased by irrelevant history;
• Poisoning: An early wrong conclusion remains in the context, and the wrong conclusion will be wrong all the way;
• Clash: The data inserted are contradictory to each other, and the model is at a loss.

3) Cost and delay increase linearly with token. Every additional token costs money and time. An Agent that fills up the context is slow, expensive, and inaccurate.

The conclusion is counter-intuitive, but extremely important:

More context is not necessarily better; a higher signal-to-noise ratio is. Context engineering is the practice of keeping only the high-signal information needed for each step.

3. What is in the context?

Let's break down the "context" first. What you see when the model is inferring is far more than the user's words, but a whole assembled window:

context engineering is to make the decision of "what to add, what to subtract, and how long to keep" for each cell in this table. One of the things that is most likely to get out of control is the "tool return result" - a web page crawl or a database query may contain thousands of tokens.

4. Four basic operations: write, select, compress, isolate

LangChain summarizes all the methods of context engineering into four types of operations. This is the best mental map currently available:

1. Write—store information outside the window

Not everything has to stay in context. Write intermediate conclusions, plans, and notesoutside the window and retrieve them when needed:

• Scratchpad: Temporary notes within the current task, allowing the model to remember "how many steps have I taken and what have I arrived at".
• Memory: Persistent information (user preferences, project conventions) across tasks and sessions.

2. Select—retrieve only what is relevant

This is the essence of RAG (retrieval-augmented generation), tool selection, and example selection:

• Instead of stuffing in the entire knowledge base, retrieve the passages most relevant to the current question;
• When there are too many tools, first use a layer of search to filter out "several tools that may be used in this step" instead of listing hundreds of tool definitions;
• Even few-shot examples can be dynamically selected based on similarity.

3. Compress—express the same information with fewer tokens

When the context is almost full, it is not roughly truncated, but compressed:

• Summary / compaction: Summarize the previous dozens of rounds of dialogue into a "current progress summary", discard the original process, and retain the conclusions and unresolved matters;
• Crop: Delete the oldest and most irrelevant parts according to rules.

4. Isolate—split context across independent spaces

Split a large task to multiple sub-Agents. Each sub-Agent takes a clean and exclusive context window to do the sub-task, and only returns the "condensed conclusion" to the main Agent. The main Agent's window therefore always looks clean. Sandboxed, standalone runtime environments also fall into this category - isolating operations that may produce massive output.

Remember these four verbs—write, select, compress, isolate—and you’ll have a toolbox for nearly any contextual problem.

In the next few sections, we will pick out the most frequently asked questions and the most common mistakes in this framework, and go into depth one by one.

5. RAG or long context? The answer in 2026

When long context window first appeared, many people asserted that "RAG is dying - why bother searching when you can fit the entire book into it?" Two years later, the conclusion is clear: long context did not kill RAG, but allowed both to return to their respective places.

• The weakness of long context is the context rot mentioned in the second section: the more stuffed it is, the easier it is to lose memory in the middle, the slower and more expensive it is. Putting all 500,000 tokens into it does not mean that the model has really "understood" 500,000 tokens.
• The value of RAG is precisely that it can select the relevant 5,000 tokens from a corpus of 500,000, producing the high-signal, low-noise context that context engineering aims for.

Practical options:

The more cutting-edge approach is agentic retrieval (intelligent retrieval): It is no longer "retrieve once, get the results and go", but let the agent conduct multiple rounds of searches by itself and judge "whether it is enough and whether to check again", turning the retrieval into a feedback loop.

6. Memory: Make Agent smarter across sessions

Memory is the part of context engineering that specifically deals with "time" and is divided into two layers:

• short-term memory: Continuity within a single session/task is mainly maintained by compaction and scratchpad in Section 4.
• long-term memory: Information retained across sessions - who the user is, what their preferences are, and what commitments the project has. Behind the "remember your preferences" you see in ChatGPT and Claude is a mechanism of writing (what is worth remembering) + retrieving (what should be remembered this time).

The difficulty in memory is never "storage", but two judgments:

1. What to write: Not all dialogues are worth remembering, and random memorization will contaminate future context;
2. What to retrieve: Which items should be remembered this time? If you retrieve too many, it will be noise.

After all, the memory system is the application of the two operations "Write + Select" in the time dimension.

7. One of the most overlooked practices: Make context cache-friendly

The previous sections have been talking about "what to put and what not to put", and there is another path that almost directly determines the cost that is often ignored - KV-cache (hint cache).

When the model processes the context, it calculates the prefix into a reusable intermediate state (KV-cache). As long as the context prefix of this round is exactly the same as that of the previous round, this part can directly hit the cache without having to recalculate - it is fast and economical (the hit token is usually only charged at a fraction of the original price). In a multi-step Agent, each step carries almost the same system prompts and history, and the cache hit rate almost directly determines billing and latency. There is even a saying in the industry: "KV-cache hit rate is the most important single indicator for production-level Agents."

This leads to several construction principles that are equally important as "signal-to-noise ratio":

• Stable things are placed in the front, and volatile things are placed in the back. System prompts and tool definitions that remain unchanged in each round are fixed at the front to ensure the stability of the prefix.
• Only append, not rewrite. New information is appended to the end; once you go back and change the previous content (even if only one timestamp is changed), all subsequent caches will be invalid.
• Compression requires timing. Compaction and cropping will rewrite the prefix and invalidate the cache, so don't trigger it too frequently, and do it once at a cost-effective point.

In a word: context engineering not only determines "whether the model is accurate", but also directly determines "whether the system is expensive or not."

8. In practice: two common patterns

Pattern 1: Compaction. This is the lifeline of long-running tasks. Take Claude Code as an example: when the context window is nearly full, it does not simply stop. It summarizes the work so far into a compact handoff record—files changed, current state, and next steps—then continues from that record. The key is to retain open issues and important decisions while discarding the raw process. Poor compaction makes an agent forget its progress and repeat work.

Pattern 2: Sub-agent context isolation. The main agent orchestrates while a sub-agent handles a context-heavy task, such as reading 20 files to find bugs. The sub-agent works in a clean window and returns only its condensed conclusions. The main agent's context is never flooded by all 20 files. This is the power of isolation—and one of the most underrated benefits of multi-agent systems: they are a context-management technique, not merely a way to run work in parallel.

9. What is its relationship with these concepts?

context engineering is surrounded by a ring of confusing words. There is no need to memorize it by rote, just sort it out according to the "type of relationship", and the boundaries will naturally be clear:

① Upstream and downstream - MCP supplies materials from below, and Harness takes care of the details from the outside.

• MCP (Model Context Protocol): Solve the problem of "what can be connected", using a unified protocol to connect external tools and data sources in a standardized manner, which is the "source" of context.
• Harness (the engineering shell of the agent): In addition to the model weight, all the engineering (tools, status, verification, context management...) that determine whether the intelligence can be stably implemented. Context management is only one of the subsystems, but it is often the first to overturn.

② Subset - prompt engineering and RAG, are part of it, not itself.

• prompt engineering: Predecessor and subset of context engineering. The task has changed from "asking and answering" to "running dozens of steps independently", and the main battlefield has expanded from "writing that sentence" to "managing the entire window."
• RAG (Retrieval Enhancement): It is just a specific method in the "select" type of operation, responsible for "fetching relevant knowledge on demand". It is a subset of context engineering, not a synonym - equating the two misses out the other three categories of writing, compression and isolation.

③ Alternate route - context engineering vs fine-tuning.

There are two fundamentally different ways to inject knowledge and capabilities into the model: feeding it into the context (in-context, all discussed in this article), or training into the weights (in-weights, that is, fine-tuning).

• Knowledge is updated quickly, sources must be brought, and additions and deletions must be made at any time → use context (RAG/long context);
• To solidify a stable style, format or proprietary capability, and the data is sufficient → consider fine-tuning.

Most mature systems use both: fine-tuning determines the "base color", and context engineering feeds the "current thing".

Concluding in one sentence: context engineering determines the "field of view" of each step of the model - prompt engineering and RAG are its parts, fine-tuning is its other way, MCP supplies materials below, and Harness takes care of the outside.

10. Ready-to-use context checklist

• Can I explain clearly what components the model has in the context it sees at each step?
• Have the results returned by the tool been "slimmed down" (leaving only conclusions and truncating overly long output)? Or just stuff it back as it is?
• Is there any "history that is no longer useful" in the context? Is there any regular compression/cropping?
• Is there a compaction mechanism for long tasks? Are open items and key decisions retained during compression?
• Is knowledge retrieval "full stuffing" or "retrieval on demand"? Do the search results include sources?
• Are the tools/examples "available in full"? Is it possible to dynamically filter based on the current step?
• Have you offloaded the heavy work to the sub-Agent and used independent windows to isolate the massive intermediate information it generates?
• Is the context "stable content first and only appended at the end" to hit the KV-cache as much as possible and suppress costs?
• Am I on the right side between "longer context is better" and "higher signal-to-noise ratio is better"?

Models will keep getting smarter and context windows will keep growing. But as long as attention remains limited and information remains noisy, an agent's ceiling will depend not only on the model itself, but on the context you feed it.

References

• Andrej Karpathy, Tweet about "context engineering" (2025)
• LangChain, Context Engineering for Agents (Write/Select/Compress/Isolate framework)
• Anthropic, Effective context engineering for AI agents
• Chroma, Context Rot: How Increasing Input Tokens Impacts LLM Performance (2025)
• Liu et al. (arXiv), Lost in the Middle: How Language Models Use Long Contexts (2023)

"If all you have is a hammer, everything looks like a nail." -Abraham Maslow (Charlie Munger loves to quote this saying and calls it the "hammer syndrome")

The smartest brains in human history are scattered in different disciplines: philosophers have honed questioning techniques for more than two thousand years, mathematicians have invented the most rigorous reasoning tools, physicists are best at simplifying the complex world into computable models, and psychologists specialize in studying where our brains go wrong.

The problem is that these methods are scattered in their respective fields, and few people put them in the same toolbox. Munger calls this "Latticework of Mental Models": You don't need to be an expert in every field, but you need to master the most important models in each field and know which one to use when.

This is what this article does - take the most important thinking methods from philosophy, mathematics, physics, psychology, economics, biology, and engineering, and then string them together according to the six stages of a complete thinking:

Define the problem → decompose and model → reason and explore → validate and correct → decide and act → review and iterate

Any serious thinking—whether it’s making technology selections, writing an article, or deciding whether to move to another city—will generally go through these six steps. At every step, there is a discipline that has polished a handy tool for you.

The article first explains the genealogy of this set of stages (I did not invent it, it has been passed down for more than a hundred years), and then introduces the tools of each stage one by one - each item is accompanied by a genealogy note: where it comes from and how strong the foundation is. The foundation of several of them is still a philosophical unsolved problem. Knowing this will make you use it more clearly.

Before setting off, go back to the hammer at the beginning. The solution to the hammer problem has never been to have more hammers—the more tools you have, the higher the chance of returning to a familiar one when you panic—but rather an index that tells you which item to reach for when. The six stages are that index.

Chapter 0: Where the framework comes from

Be honest about your family tree: The six stages are not a natural law of thinking, but a normative model - it describes "how you should think", not how the brain actually works (the brain is parallel, jumping, and driven by emotions). This model has a clear line of inheritance:

• Dewey's "How We Think" (1910) proposed five steps of reflective thinking: feel difficult → define the problem → formulate a hypothesis → reason → test. This is the direct ancestor of stages one to four of this article. Dewey's most important insight was to separate "feeling difficulty" and "defining the problem" into two steps - what you initially feel is never the problem itself, just the symptoms.
• Polya's "How to Solve Problems" (1945) provides four steps for solving mathematical problems: understand the problem → make a plan → execute → review. "Review" is one of the sources of Stage Six.
• PDCA cycle, OODA cycle, design thinking and other twentieth-century engineering and management variants have contributed one thing together: incorporating "action" into the cycle of thinking, rather than treating it as the end point of thinking.

Distilling all these solutions to the bottom, there is only one algorithm left in the core: Generate-Verify-Retain. Popper called it "conjecture and refutation", psychologist Donald Campbell called it "blind mutation and selective retention", and evolution is its unconscious version - as you will see later, the third, fourth and sixth stages are the core itself, the first and second stages are the problem construction front end added by Dewey, and the fifth stage is the action back end added by decision theory.

The insertion of the fifth stage hides the hardest dividing line in the entire framework. Its basis comes from Hume: What is cannot deduce what should be. From stage four to stage five, there is a category switch in thinking - the first four stages ask "what is true" (cognitive rationality), and the fifth stage asks "what should be done under the constraints of scarcity" (practical rationality). No matter how perfect the verification is, it will not automatically tell you which one to choose, because "should" must introduce values ​​and constraints. The other stage boundaries are all gradual, but this one is a cliff.

One last reminder: the stages are spirals rather than straight lines. When you get to the back and find that you made a mistake at the front, go back and start again - the instructions at the end of the article will return to this point.

Stage One: Defining the Problem—The Territory of Philosophy

There is a saying that is widely attributed to Einstein but is actually unsubstantiated: If I were given an hour to save the world, I would spend fifty-five minutes figuring out what the problem was. No matter who it comes from, the truth is true - most low-quality thinking fails in the first step: solving a wrong problem.

1. Socratic questioning: pin down vague terms

The first tool of philosophical contribution is the method Socrates used all his life on the streets of Athens: Continuously ask "What do you mean by X?" for each key concept.

"I want to make a better product" - what does "better" mean? Better for whom? What is the measure? "Team efficiency is too low" - "efficiency" refers to delivery speed, unit output or rework rate? You will find that in many arguments that last for three hours, the two sides are not talking about the same thing at all. Until the concept is nailed down, all discussions are in vain.

_Genealogy: "elenchus" in Plato's dialogues, fifth century BC. It implies a presupposition that concepts all have a definable essence; more than two thousand years later, Wittgenstein used "family resemblance" to refute: most everyday concepts (such as "game") have no unified definition at all. Therefore, when nailing a concept, what we seek is not a perfect definition, but "everyone uses the same definition in this discussion." _

2. First-principles thinking: reduce the problem to irreducible facts

This word originated from Aristotle and was popularized by Musk: Don't reason from "everyone does this" (analogous thinking), but start from "which facts are physically determined to be true" and start from the beginning.

The classic case is batteries: analogical thinking says "batteries have always been expensive in history, so they will be expensive in the future"; first-principles thinking asks "What raw materials are batteries made of? How much are these raw materials worth in the market?" - the answer is that the material cost only accounts for a small part of the selling price, and the rest are links that can be redesigned.

_Genealogy: ἀρχή (origin) in Aristotle's "Metaphysics"; "Post-Analysis" advocates that all proofs must ultimately fall on self-evident starting points - this is the source of "foundationalism" in the theory of knowledge, and Descartes's universal doubt is the same action. But the foundation is not as solid as it sounds: the "Agrippa's Trilemma" of ancient Greek skepticism states that any chain of justification must either go back infinitely, cycle, or stop arbitrarily. In practice we choose the third option, so remember: your "fact list" itself can be wrong. _

3. Reframing: what are you really trying to solve?

There is also a simple but sharp habit in philosophical training: distinguishing between surface issues and underlying issues. The elevator is too slow, so the superficial solution is to change the elevator; but the underlying problem may be that "waiting makes people irritated", so a mirror is installed next to the elevator, and the complaints disappear. Before taking action, ask one more question: "Is this problem a symptom of a larger problem?"

_Genealogy: Dewey's "How We Think" divides "feeling difficult" and "defining the problem" into two independent steps, which is to admit that the two are often inconsistent; design thinking institutionalizes this step as "problem reframing". _

Output at this stage: Write clearly in one sentence "The problem I want to solve is _, and the criterion for judging whether it is solved or not is _". If you can’t write it, don’t move to the next stage.

Stage Two: Decomposition and Modeling—Mathematics and Physics

Even after a problem is clearly defined, it is often still too large and complex. The task of the second stage is: make it smaller, simpler, and actionable.

4. Abstraction and divide-and-conquer: the mathematician's two tools

Abstraction is the ability to discard irrelevant details and retain only the skeleton of the problem. Mathematicians don't care whether it's seven apples or seven cows, they only care about "7". When faced with a complex problem, ask first: What is the structure of this problem after removing all surface information? Does it look like a problem I already know how to solve?

Divide and Conquer (Divide and Conquer) is to cut a large problem that cannot be solved into several small problems that can be solved. The key is that the cuts should be "orthogonal" - the sub-problems should not be entangled with each other as much as possible, otherwise if they are cut, they will not be cut.

_Genealogy: Abstraction has been the essence of mathematics since Euclid. The classic expression of divide and conquer is the second rule of Descartes' "Discourse on Method" (1637) - "Divide each difficult problem under consideration into as many small parts as possible until it can be properly solved." It became the pillar of algorithm design three hundred years later. _

5. Idealized model: Physicist’s “frictionless slope”

The core method of physics is not mathematics, but dare to simplify. When Galileo studied falling bodies, he assumed there was no air resistance. Mechanics was full of "particles", "rigid bodies" and "ideal gases" - all things that did not exist in reality, but it was these "wrong" models that made the problem solvable.

The practical version is: Build a rough but calculable model first, and then gradually add back the ignored factors. First assume that users are rational, the network will never jitter, and needs will not change, and run through the main logic; then return to the complexity of reality one by one to see which one really changes the conclusion.

Genealogy: Galileo's ideal slope is the starting point of modern science - he was the first to realize that "first studying a simplified world that does not exist" is more effective than directly facing the chaotic reality. Statistician George Box summed up what became the norm: "All models are wrong, but some are useful."

6. Fermi estimation and dimensional checking: fast approximation of orders of magnitude

Fermi could train his students with questions like "How many tuners are there in Chicago?" by dividing an unattainable quantity into several factors that can be roughly estimated and multiplied together. The errors will cancel each other out, and the results are often correct by orders of magnitude. Many decisions don’t require an exact answer, just knowing whether it’s 10 or 10,000.

The supporting tool is dimensional analysis: after completing the calculation, check whether the units are correct and whether the order of magnitude is reasonable. An estimate of "3 million new users per day" multiplied by 365 days becomes ridiculous. This is a cost-effective error correction method.

_Pedage: The estimation method is named after Fermi; the source of dimensional analysis is Fourier, developed by Rayleigh, and systematized by Buckingham's π theorem (1914) - the dimensions of both sides of the physical equation must be consistent. This simple constraint is so strong that the shape of the formula can sometimes be directly guessed. _

Output of this stage: a simplified model or disassembly diagram - you know which factors are retained and which ones are temporarily ignored.

Stage Three: Reasoning and Exploration—Deduction, Induction, and Thought Experiments

The model is built, now we need to reason on the model and generate candidate answers.

7. Deduction, induction and abduction: three reasoning engines

Logic distinguishes three types of reasoning: deduction (from the general to the specific, if the premises are true, the conclusion must be true), induction (summarizing the rules from the sample, the conclusion is only a high probability), abduction (working backwards from the results to the most likely cause - it is used by doctors to diagnose and engineers to troubleshoot bugs; when candidate explanations are fighting, Occam's razor is used first: the one with the fewest assumptions is given priority).

The key is not which one to use, but to know which one you are using at the moment. Treating the summarized experience as a deductive iron rule ("The first three times were caching problems, this time must be the same") is the most common trap when troubleshooting problems.

_Genealogy: Deduction originated from Aristotle's syllogism and was completely formalized by Frege in 1879; abduction was named by Peirce at the end of the 19th century, and Harman later called it "inference to the best explanation" - but there is still no generally accepted answer to "why the best explanation is more likely to be true"; Occam's razor is named after the fourteenth-century scholastic philosopher William of Ockham, and the popular expression "Do not add entities unless necessary" is actually a refinement of later generations. The foundation of induction is one of the most famous collapses in the history of philosophy: Hume (1748) proved that "as it was in the past, so it will be in the future" cannot be proved non-circularly - you can only use induction itself to defend induction. This is the "problem of induction". The main responses - Kant's transcendental categories, Popper's falsificationism (section 11), Bayesianism (section 15) - will be encountered later, and Goodman's 1955 "Green-Blue Paradox" demonstrated that the problem went deeper than Hume said. Even deduction is not immune: Lewis Carroll's What the Tortoise Said to Achilles (1895) shows that the rules of inference themselves cannot be justified by reason. We used these three engines, but none of them had their foundations welded shut. _

8. proof by contradiction and extreme situations: a mathematician’s probe

proof by contradiction: Let’s first assume that the conclusion is not valid and see what absurdity will be derived. The everyday version is "Suppose this solution is wrong, what is it most likely to be wrong about?" - this is more likely to expose blind spots than positive arguments.

Extreme case test: Push the parameters to 0 and push them to infinity to see if the conclusion still holds. "If the number of users is 1,000 times the current number, where will this architecture collapse first?" "If only one person is left to maintain it, can this process still be transformed?" Extreme values ​​are the cheapest stress test.

_Pedage: The earliest known masterpiece of proof by contradiction is the Pythagorean school's proof that "√2 is an irrational number"; the law of contradiction it relies on is called "the most certain of all principles" by Aristotle. One exception worth knowing: the intuitionist mathematician (Brouwer) rejects one type of usage that does not allow the direct assertion of "existence" from "non-existence would lead to a contradiction." This commandment is not needed for everyday thinking, but it reminds us that even the boundaries of proof by contradiction have been seriously debated. _

9. Thought experiments and symmetry: the imagination of physicists

Einstein ran after light and came up with the theory of relativity; Maxwell raised a "demon" that sorted molecules. Thought experiments are to build a laboratory in the mind and use imagination to run experiments that cannot be done in reality. The counterpart in decision-making is the philosopher Rawls' "veil of ignorance": If you didn't know which party you would be under this rule, would you still make this rule?

Physics also contributed to the intuition of symmetry and conservation: the search for invariants in change. No matter how complex the system is, some things are always conserved - total budget, total time, and trust. "This plan claims to be a win-win situation for all three parties, so who will the cost be transferred to in a conservation-oriented manner?"

_Genealogy: The first masterpiece of thought experiment came from Galileo - "Heavy objects fall faster" can deduce the contradiction purely through imagination (tie two large and small stones together, and according to Aristotle's theory, it will be faster and slower at the same time); the term "thought experiment" (Gedanken experiment) was coined by the physicist Oersted, and it became a conscious methodology through the hands of Mach; its epistemological status is still debated. Norton believes that thought experiments are just arguments in disguise. The "veil of ignorance" comes from Rawls's A Theory of Justice (1971). The foundation of conservation intuition is the hardest among the tools in the whole text - Noether's theorem (1918): each continuous symmetry strictly corresponds to a conserved quantity (time translation symmetry ⇒ conservation of energy). It's a proven theorem, not a heuristic; applying conservation to budgets and trust is certainly an analogy, but the analogy's parent is extremely reliable. _

10. Reverse thinking: think the other way around, always think the other way around

Mathematician Jacobi's famous saying "Invert, always invert" was adopted by Munger as his lifelong creed. Instead of asking "How can I make the project succeed?" start by asking "How can I ensure it fails?" - and then avoid every item on the list. The path to failure is far more clear and enumerable than the path to success.

Munger's most famous demonstration was his graduation speech at Harvard-Westlake School in 1986: when others talked about how to obtain happiness, he talked about "how to ensure that you live a miserable life" - jealousy, resentment, capriciousness, not learning from the lessons of others, and being unable to recover after encountering setbacks. Implementing each one in reverse is the answer.

_Genealogy: Jacobi was originally talking about mathematical practice - many problems have simpler structures from the opposite side. Behind this is the ubiquitous duality in mathematics; Munger moved it from mathematics to life and investment. _

Output of this stage: more than one candidate solution. When there is only one option, you are not actually thinking, you are just obeying.

Stage Four: Validation and Correction—Science and Psychology

At this point you already have a few candidate answers that look good. The whole point of Stage 4 is this: The most important thing your brain wants to do at this moment is prove that it is right, and you have to force it to do the opposite.

11. falsifiability: Popper’s dividing line

The philosopher of science Popper pointed out that the dividing line between science and non-science lies not in "whether it can be verified", but in "whether it can be falsified". A theory that is right no matter what ("It's all fate") conveys no message.

Practical method: Write a falsification condition for your conclusion - "If X is observed, I admit that this judgment is wrong." A judgment that cannot write X is not called a judgment, it is called a belief. Then, go for X instead of waiting for it to hit you.

Popper's own epiphany came from a real comparison: In 1919, Eddington led an expedition to observe the total solar eclipse to test the starlight deflection predicted by the general theory of relativity - Einstein stuck his neck into the guillotine and died if the data did not conform to the theory; while the Freudian theory of the same era, in Popper's view, could be justified no matter how the patient behaved. The dividing line is drawn between those who dare to be killed and those who are always right.

_Genealogy: Popper, "The Logic of Scientific Discovery" (1934). It's worth knowing its motivations: Popper accepted Hume's verdict on induction in its entirety (see Section 7), and then took the next step - science does not rely on induction at all, theories are always just conjectures, and the entire rationality of science lies in the efficient elimination of wrong conjectures. The subsequent important revision was the Dion-Quine thesis: a single hypothesis can never be falsified in isolation, and you can always blame an auxiliary hypothesis ("the instrument is broken"); Lakatos distinguished between "progressive" and "degenerate" research programs - a belief that survives by constantly patching is degenerate. Doing this check on your own beliefs is quite cruel and quite effective. _

12. Confirmation Bias and System 1/System 2: Know Where Your Brain Lies to You

Psychologist Kahneman divided thinking into two systems: System 1 is fast, automatic, and intuitive; System 2 is slow, laborious, and logical. The trouble is that System 1 is always on and good at masquerading as rationality—you think you’re reasoning, but you’re actually making excuses for your intuition.

The most dangerous biases are worth naming: confirmation bias (only seeing evidence that supports oneself), anchoring effect (the first number kidnaps subsequent judgments), loss aversion (the pain of loss is about twice as much as the pleasure of the same gain, so people will cling to sunk costs), survivor bias (during World War II, the military wanted to armor the parts with dense bullet holes on returning bombers, statistician Wald pointed out that the parts that should be reinforced were precisely the parts without bullet holes - the planes that were hit in those places failed to fly back). The first step in correcting mistakes is not to "try harder to be objective", but to admit that there is a high probability that you are biased at the moment, and then use processes to hedge against it - such as forcing you to write down the opposing view, or finding someone who really dares to speak up to be a red team.

_Genealogy: Kahneman and Tversky pioneered the "heuristics and biases" research program in the 1970s ("Thinking, Fast and Slow" is its popular version summary); a deeper level is Simon's "bounded rationality" in the 1950s: biases are not bugs in the brain, but engineering compromises under limited computing power. Listen to the opposing side: Ji Renze argued that many heuristics are "ecologically rational" in real environments, faster and often more accurate than complete calculations; the universality of "loss aversion is about twice as much" has also been debated in recent literature. Conclusion: The deviation list is a guidepost, not a verdict. _

13. Correlation does not equal causation: appearing together does not mean who caused whom.

The bias in the previous section is that your brain actively deceives you. The trap in this section is hidden in the data: Two variables always rise and fall together, which does not mean that one of them causes the other. Ice cream sales are highly positively correlated with the number of drownings, but it is not ice cream that causes people to drown - it is the common cause of "summer" (confounding variable). Seeing the correlation, there are at least four possible coexistences: A causes B, B causes A, and the third factor C drives both at the same time, which is pure coincidence.

Practical discipline: Look for confounding variables before taking action, and ask "Is there a C that drives both sides at the same time?" If you can do a randomized controlled experiment (randomly divide the sample into two groups), do it. If you can't do it, then lower the credibility of the conclusion by one level. A hidden variant is Simpson's Paradox - the same data can lead to completely opposite conclusions when viewed in groups and combined.

_Genealogy: Hume has long pointed out that we never "see" cause and effect, only constant succession (again the source of the induction problem in Section 7); what turned causal inference into an operational tool was statistics - Fisher's randomized controlled experiments (1920s) and Judea Pearl's causal diagrams and do-calculus (1990s). Everyone knows "correlation does not imply causation", but the difficulty has always been to identify the specific confounding variable. _

14. External perspective and basic probability: first look at your peers, then look at yourself

There are two ways to predict how something will end. Internal Perspective Focus on the details of the matter itself and deduce: "Our team is strong, the plan is thorough, and we can go online in three months." External Perspective First ask: "What is the usual outcome of similar things?" - How many projects of similar scale are online on time? What is the median number of deferrals? Humans naturally prefer an internal perspective, and it is systematically over-optimistic. This is the planning fallacy: almost every big project is over time and over budget because every team feels that "we are different."

There is only one corrective action: for any prediction, first find a reference class for it, use the true distribution of this group of similar people as an anchor, and then make limited adjustments based on the particularity of this case. Basic probability is your starting point, not a background that can be skipped.

Kahneman told his own experience: He led a team to compile a textbook, and the team optimistically estimated that it would be completed in two years; he asked a senior member, "How long does it take on average for similar projects you have seen, and how many of them aborted halfway?" The answer was seven to ten years, and about 40% of them were aborted. They didn't take this external data seriously, and it took eight years - even though they knew the basic probability, they still lost to the internal perspective.

_Genealogy: Kahneman and Lovullo distinguished "external perspective vs. internal perspective" in 1993; its operationalization is reference class forecasting, which Frufbeagle uses to systematically improve cost estimates of large-scale infrastructure, and has been written into specifications by many governments. It's the same thing as Bayes in the next section: the outside perspective gives you a decent prior, and Bayes tells you how much to move it when you get new evidence. _

15. Bayesian updating: maintaining beliefs as probabilities

The everyday version of Bayes' theorem is this: Beliefs are not black-and-white switches, but probabilities that slide with the evidence. Ask three questions when you get new evidence: What was my original confidence (prior)? If I'm right, what are the chances of seeing this evidence? What if I'm wrong?

Keynes (according to legend) said: "As the facts change, my thoughts change. What about you, sir?" The virtue of a Bayesian is not to stand firm, but to update quickly and to the right extent - not overturning it entirely because of one counterexample, nor remaining unchanged despite ten counterexamples.

This simple algorithm has found aircraft wreckage: Air France Flight 447 crashed into the Atlantic Ocean in 2009, and two years of search found nothing; in 2011, the search party invited Bayesian search experts to use every previous failure as evidence to update the probability distribution of wreckage hidden in various areas of the seabed, and the fuselage was found within a week of the start of a new round of searches. The same method was used to locate the sunken nuclear submarine "Scorpion" in 1968.

_Genealogy: Bayes (posthumous 1763) and Laplace. It has two rare and hard proofs: Cox's theorem proves that the "credibility" operation that satisfies several rationality axioms must be probability theory; De Finetti's "Dutch Gamble" argument proves that people who do not act according to the axioms of probability can be harvested by constructing a set of gambling games that are guaranteed to make money without losing money. In other words: Refusing Bayesian updating is not just stubbornness, it is stubbornness that can be priced at. _

16. pre-mortem: Hold a memorial service before failure occurs

Premortem (pre-mortem) invented by psychologist Gary Klein: Before the project is launched, everyone assumes that "it is now one year later and this project has failed miserably", and then everyone writes down the reasons for the failure. This simple change of frame can turn "raising concerns" from a disappointment to a task, and uncover risks that no one usually dares to mention. It can also be used by one person: Write a letter of failure to yourself one year from now.

Klein recorded an example in the original article: A Fortune 50 company launched a billion-dollar sustainable development project. At the pre-mortem meeting, an executive wrote that the cause of death was that once the CEO who supported it retired, the project would lose its backer. No one dared to say this at the mobilization meeting, but blurted it out at the "memorial service".

_Genealogy: Klein, published in Harvard Business Review in 2007; based his experiment on a 1989 study on "prospective hindsight"—which allows people to assume that an effect has already occurred and imagine the cause in a much more concrete way. _

The output of this stage: a list of falsification conditions + a pre-mortem report. Only if your plan is still standing after being attacked by yourself will you be qualified to enter the decision-making process.

Stage Five: Decision and Action—Economics and Engineering

There may still be several verified solutions, but only one resource. The fifth stage switches from "truth seeking" to "weighing" - remember Hume's cliff in Chapter Zero? Just cross over from here.

17. Opportunity cost and marginal thinking: two cornerstones of economics

Opportunity cost: The true cost of a choice is not what you paid, but the best option you gave up as a result. "Is this thing worth doing?" is a pseudo question. The real question is "Is this thing worth doing more than other things I can do?"

Marginal Thinking: Decision-making always depends on the increment, not the total amount. Don't ask "Do you want to do marketing?", ask "How much more can you get back if you invest more of this dollar in marketing?" Accompanied by this is the iron law of sunk costs: the money you have spent, the emotions you have invested, and the code you have written have nothing to do with future decisions—even though loss aversion will try your best to make you feel that they are.

The most famous move to cut sunk costs occurred at Intel in 1985. Memory is the business where the company started. It has been beaten back by Japanese manufacturers, but no one can stop it. Grove asked Moore: "If the board of directors replaced us, what would the new CEO do?" Moore replied: "Exit the memory." Grove said: "Then why don't we walk out of this door ourselves, walk back, and do it ourselves?" The new CEO does not carry old scores-the whole content of this ideological move is to zero out the sunk costs. Intel has since moved on to processors.

_Genealogy: The "marginal revolution" in the 1870s - Jevons, Menger, and Walras independently proposed it almost at the same time. Economics has since shifted from "what determines value" to "how increments are compared"; opportunity cost was named by Wieser. The foundation is the axiom of scarcity: as long as resources are limited, choice must mean giving up. _

18. Expected value and asymmetry: living with uncertainty

The skeleton of rational decision-making is expected value: payoff × probability. But real masters also look at the shape of the distribution - Taleb calls it asymmetry: things with limited downside and huge upside (writing, open source, goodwill in social circles) are worth doing repeatedly; things with limited upside and fatal downside (leverage, single point dependence, gray areas) are too many once. Never risk getting kicked out, no matter how good the expectations are.

The negative teaching material is Long-Term Capital Management (LTCM): there are two Nobel Prize winners in economics on the partner list, and the expected value of each arbitrage is positive, so it adds about 25 times leverage to make repeated bets. When Russia defaulted on its national debt in 1998, a tail event completely kicked it out of the game, and the Federal Reserve finally stepped in to organize a rescue. The expectations of each step are right, but what is wrong is that they are playing a game that does not allow them to lose even once.

_Genealogy: In 1654, Pascal and Fermat corresponded about the gambling problem, which gave birth to probability theory; in 1944, von Neumann and Morgenstern completed the axiomization of expected utility. The shortcomings of naked expected value were exposed very early - Bernoulli's St. Petersburg Paradox in 1738; and the modern mathematical basis for "don't risk being out" is the ergodic problem (physicist Peters): The time average is not equal to the set average, and a gamble with a positive expected value can be devastating to individuals who must make continuous bets. This is what Taleb said. _

19. Incentives and games: There are people on the opposite side

Opportunity cost and expected value both imply that you are dealing with "nature" - costs and probabilities will not change because of your choices. But across from most real decisions, there are people who will predict and respond to you. At this time, two additional checks are required. The first is Incentives: To judge what a person or organization will do, looking at its incentive structure is far more reliable than listening to its promises - Munger's version is "show me the incentives and I will show you the results." The second is Opponent's optimal response: Count other people's reactions into the plan - "If I lower the price, will my opponent follow? Will I still make money after following?" A plan that does not consider responses is written for a static world.

A textbook case of incentives overriding slogans is Wells Fargo Bank in 2016: the headquarters set a hard target for tellers to "cross-sell eight products per customer" and linked it to salary, so employees opened about 3.5 million false accounts without customers' knowledge. Everyone is responding rationally to incentives, which adds up to a disaster - the slogan is about serving customers, the incentive award is the number of accounts opened, and employees listen to incentives. This is Goodhart's Law: Once an indicator is used as an assessment target, it will be optimized for numbers, and it will no longer be the thing it was originally intended to measure.

_Genealogy: Game theory and expected utility in Section 18 come from the same book - von Neumann and Morgenstern's Game Theory and Economic Behavior (1944); Nash's 1950 concept of equilibrium generalized it to non-zero-sum situations. The academic version of "looking at incentives" is mechanism design theory (Hurwitz, Maskin, Myerson, 2007 Nobel Prize in Economics): simply treat incentives as objects that can be designed. _

20. Reversible and irreversible: Bezos’ two doors

Bezos divides decision-making into two categories: two-way doors (you can go back if you make a mistake) and one-way doors (you can't go back when you go through them). Two-way door decisions should be fast, cheap, and delegated to the nearest person - the cost of delay at this time is much higher than making a mistake; only one-way door decisions are worth slowing down and using all the tools in the first four stages. The problem most people have is that they treat two-way doors with the caution of a one-way door, but walk through a one-way door with the carelessness of a two-way door.

Amazon's own example of a one-way door is Prime in 2005: the financial model is not fair no matter how you calculate it, and once "free two-day shipping" is given out, it is almost impossible to get it back - taking away existing benefits from users is much more costly than never giving them - Bezos asked the team to deduce it repeatedly before making a decision. In contrast, the hundreds of interface experiments that run every day on Amazon's website are a standard two-way door: ugly data, offline for the day.

_Genealogy: Bezos’ 2015 Annual Letter to Shareholders. The academic counterpart is Simon's "satisficing": the optimal strategy for a bounded rational person is not to seek the best in everything, but to allocate cognitive budget according to the importance of the decision. _

21. The engineer’s art of compromise: there is no optimality, only trade-offs

The core worldview of engineering contributions is: All designs are trade-offs, and you can only choose two: fast, good, or cheap. The supporting method is Minimum Viable Product (MVP): when analysis cannot continue to reduce uncertainty, stop analysis, use the minimum cost to push the plan into reality, and let reality take over verification - doing it is itself a higher-bandwidth thinking.

Both textbook cases are included in "The Lean Startup". When Dropbox's products were not yet available for public use, founder Houston first released a three-minute demonstration video, and the waiting list grew from 5,000 to 75,000 people overnight - not one more line of code was written, and the demand was verified. The founder of Zappos first went to a nearby shoe store to take photos of the shoes and put them on the shelves. When someone placed an order, he bought them at the original price and sent them out. The zero inventory proved that "someone is willing to buy shoes online."

_Genealogy: MVP was popularized by Eric Rice in "The Lean Startup" (2011), but its philosophical roots are much older - the pragmatism of Peirce and Dewey: the meaning of an idea lies in its practical effect, and action is not the end of inquiry, but a part of it. _

Output of this stage: A clear decision + its opportunity cost + what kind of door it is + minimal first step.

Stage Six: Review and Iteration—Cybernetics and Evolution

Action is not the end of thinking, but the input for the next round of thinking.

22. Feedback loops: the heart of cybernetics

Wiener's cybernetics boils down all intelligent behavior to feedback: the output is measured, compared with the target, and the error is sent back to correct the input. This is how missiles catch up with airplanes, how thermostats stabilize temperatures, and how people learn to ride bicycles.

The corollary is practical: the rate at which a system progresses depends on the speed and fidelity of its feedback loop. A system with a one-year feedback cycle (annual performance) is destined to evolve less quickly than a system with a one-day feedback cycle (daily review). The most powerful way to improve something is often not to work harder, but to shorten its feedback loop.

_Pedage: Wiener's "Cybernetics" (1948); an earlier mathematization was Maxwell's 1868 "On the Governor" - written to analyze the centrifugal governor of Watt's steam engine and regarded as the first paper on control theory. _

23. Mutation-selection-retention: the algorithm of evolution

Darwin gave us perhaps the most powerful problem-solving algorithm ever devised, which requires no intelligence whatsoever to create eyes and brains: Generate variation→Environmental selection→Keep the winner→Repeat.

Applied to individuals and organizations: Keep diverse attempts at a low cost (mutation), use real-world feedback rather than internal opinions to filter (selection), and solidify proven practices into habits and processes (retention). Note that all three are indispensable - only mutating without retaining is a fool's errand, only retaining without mutating is rigid.

The most complete three-shot ensemble in business history is the Post-it note: Silver, a chemist at 3M, invented a "failed" weak glue that could not stick (mutation); a few years later, his colleague Fry used it to bookmark the choir's hymnbook, and found that "it sticks and can be peeled off without leaving traces" is exactly what countless people need (choice); 3M solidified it into a permanent product line, which sells well to this day (retention). There is also an answer to where the variation comes from - 3M allows employees to spend 15% of their working hours on self-chosen projects: the organization cannot design the variation itself, but it can design the environment in which variation can occur.

_Genealogy: Darwin's "The Origin of Species" (1859); Campbell promoted it in 1960 as "blind mutation and selective retention" - a universal algorithm for the growth of all knowledge. Note that it is isomorphic with Popper's "Conjecture and Refutation" in Section 11: Conjecture is mutation, and refutation is selection. This is no coincidence - this is the engine mentioned in Chapter Zero, and the same algorithm is running deep within the entire six-stage framework. _

24. Metacognition and deliberate practice: thinking about thinking itself

The closing gift of psychology is metacognition: the ability to monitor one's own thought processes. When reviewing, you should not only ask "Was the result correct?" but also "Was my thinking process correct?" - Good decisions may have bad luck, and bad decisions may also have good results. Poker player Anne Duke calls confusion between the two "resulting", which is the most hidden mistake in review. Duke's book begins with a real precedent: In the last 26 seconds of the 2015 Super Bowl, the Seahawks chose to pass the ball on the one-yard line instead of rushing on the ground. They were intercepted by the opponent and lost the championship. Head coach Carroll was scolded as "the stupidest decision in history." Its twin trap is mean reversion: extreme results are likely to be followed by more mediocre results. This is a purely statistical phenomenon - attributing the drop after the outbreak to "your own laxity", and the rebound after the trough to "effective corrections", and review becomes making up stories for the noise.

Research on deliberate practice reminds: Mere repetition does not produce progress, only repetition with clear goals, focusing on weaknesses, and obtaining immediate feedback does. Thinking methods themselves are skills, and this law also applies.

_Genealogy: Metacognition was named by Flavell in 1976; mean regression was discovered by Galton (1886) in the study of height inheritance; deliberate practice was Eriksson's research program in 1993 - the "10,000-hour rule" was a simplified paraphrase of Gladwell, and Eriksson himself did not admit it; subsequent meta-analysis (McNamara, 2014) showed that the difference in performance explained by deliberate practice is much smaller than the popular statement. The direction is effective, but the amplitude is not magical. "Resulting" comes from Anne Duke's "The Bet" (2018). _

Output of this stage: Write it down. A review that is not written down will be tampered with by memory into "I expected it" two weeks later (hindsight bias, the final blow of psychology).

The complete framework: a cheat sheet

Three instructions for use:

First, the stages are spirals rather than straight lines. When the verification phase finds that the problem definition is wrong, it returns to the first phase - this is not a failure, this is precisely the process at work. Real thinking jumps repeatedly between six stages.

Second, you don’t have to walk the entire distance every time. For small decisions about two-way doors, it is enough to use intuition and a quick "think back"; only for big decisions about one-way doors, it is worth going through the six stages. When faced with a one-way door, the most leveraged step is often to first translate it into a two-way door question - "Do you want to spend a year writing a book?" and first into "Write one of the chapters into an article and send it out. Are there any strangers who are willing to read and forward it?" The latter can be answered with a minimal experiment over a weekend. The choice of tools itself is a matter of judgment.

Third, the tool does not work automatically. People who know about confirmation bias still make confirmation bias, and people who are familiar with sunk costs are still reluctant to cut their flesh. These methods can only work when you need them most and least want to use them when you need them most and least want to use them.

Munger said that his life was just "holding a few big ideas in hand and waiting patiently." Behind each of the twenty-four tools in this toolbox stands a discipline that has been polished for hundreds or even thousands of years - the foundations of some tools are still being reworked by philosophers, but this does not prevent them from being useful, just as you do not need to wait for the completion of quantum gravity to use Newtonian mechanics. You don’t need to invent new ways of thinking, you just need to reach for the right thing at the right stage.

Models keep getting smarter, so why do agents still fail so often? The answer lies in the engineering system around the model: the harness. This guide moves from concepts to practical implementation and ends with a checklist you can use directly.

1. Let’s first look at a counter-intuitive fact

The same Claude / Codex model, the same task, changing two sets of "shells", the success rate can jump from 20% to nearly 100% - the model has not changed a word.

This is a repeatedly observed conclusion in the learn-harness-engineering course (see the reference document at the bottom): for a TypeScript/React project, the success rate is about 20% when the model is only given a README; after the "rules, status, verification" shell is completed, the success rate is close to 100%. The model was not changed, only the harness was changed.

OpenAI's case is even more striking (Ryan Lopopolo, February 2026). A small team began with an empty repository in late August 2025. Over roughly five months, humans wrote zero lines of code: Codex generated every line. The result was about one million lines across application logic, infrastructure, tooling, and documentation, plus 1,500 merged PRs. The team grew from three to seven people while per-person throughput rose to 3.5 PRs per day. Rather than writing business code, the engineers focused on designing an environment in which the model could produce reliable work. They estimated that the project took about one-tenth the time of writing the code by hand.

The thing now has a name: Harness Engineering.

One sentence definition:

Agent = Model + Harness. The model is responsible for "smartness", and the harness is responsible for "reliability".

2. What is Harness?

The most common misconception is that a harness is merely a well-written system prompt or a CLAUDE.md file. It is not.

The definitions given by various companies are highly consistent, and the core is the same sentence:

Harness = In addition to model weight, all engineering infrastructure that determines "how much intelligence can be implemented". (LangChain's statement: "every piece of code, configuration, and execution logic that isn't the model itself.")

It includes but goes far beyond prompt: tool definition and execution, file system and sandbox, state persistence, verification mechanism, context management, sub-agent orchestration, deterministic hooks/middleware (compaction, continuation, lint interception and other links that do not rely on model awareness and are enforced by code), observability...

To give the most appropriate analogy:

Think of Agent as a senior engineer joining today. He's smart, but knows nothing about your code base. He needs: project documentation, a running environment, usable tools, knowing the "done" criteria, and shift records. The sum of these things is the harness. The more complete the scaffolding you provide, the closer the ability of this "new person" will be to his true level.

Key insights: Today's Agent failures were mostly not "not smart enough" but "can't see/can't run/don't know when it's over" - these are all harness problems, not model problems. This is the so-called capability–execution gap.

3. Five subsystems of Harness

A complete harness can be disassembled into five subsystems. The following five-point method is synthesized from three sources: WalkingLabs’ learn-harness-engineering course, LangChain’s component panorama, and Anthropic’s long task practice. It is recommended to self-check item by item according to the following table:

A little explanation (the divisions among different companies are not completely consistent): The original five-piece set of the learn-harness-engineering course is Instructions / State / Verification / Scope / Session Lifecycle - "Session Life Cycle" is listed as a separate item. This article changes to a method closer to LangChain/Anthropic: "Tools and environment" (which both emphasize, and most directly determines whether the Agent can run) is made a core item, and "session life cycle" is incorporated into the long task method in Section 4 (initialization/execution separation, clean restart). It doesn't matter how the subsystem is named or how many items it is classified into. It is important not to omit items.

                ┌─ Instructions  What the project is and what constrains it
                ├─ Tools/Env     What the agent can do and whether it can run
   Harness ─────┼─ State         Where the previous session stopped
                ├─ Scope         What this session will do and what counts as done
                └─ Verification  How the agent proves its work is correct

Dismantle them one by one below.

1. Instructions: Put the onboarding guide in the repository

The principle is not "the more you write, the better", but progressive disclosure: a core instruction file of about 100 lines that clearly explains what the project is, the technology stack, the first run command, inviolable constraints, and the document entry. Link out details as needed, rather than gluing an encyclopedia to the model all at once, which would only dilute attention.

Core iron rule: The repository is the only source of truth (repo as the system of record). Agent cannot turn around and ask colleagues like humans. Everything it needs must be visible in the warehouse.

2. Tools/Environment: Give less constraints and more capabilities

• Tool permissions follow least permission instead of banning them all - if the restrictions are too strict, the agent can only rely on guesswork.
• The environment must be self-describing and reproducible: the dependency files, runtime versions, and container configurations are all in place so that the Agent can start serving with one click. In Anthropic's practice, there is a dedicated init.sh responsible for pulling up the development environment.
• An underrated ability: Give Agent a sandbox that can run bash/execute code. Rather than pre-configuring a bunch of narrow tools, "being able to write code and run it yourself" is the key to universal autonomy - it can verify and debug by itself.

3. State: Handover like a shift worker

Long tasks span multiple context window, each new session is a blank slate. Anthropic likens this to "engineers working shifts without handover documentation."

The solution is to put the state on the disk:

• Progress file (claude-progress.txt / PROGRESS.md) records: what has been done, what is being done, and where it is stuck.
• Use git commits and commit messages to leave traceable traces.
• Each session starts by reading the progress and git log, and updates the progress before ending.

Effect: When there is a harness, the Agent can accurately "continue from the last breakpoint"; when there is no harness, it will either redo it or start from the beginning every time.

4. Scope: Do one thing at a time

A common problem with Agents is being greedy for too much—trying to implement too many functions at once, but not finishing any of them.

Anthropic's approach is very straightforward: split the task into 200+ extremely fine-grained feature lists, mark each item with pass/fail, and use JSON instead of Markdown (JSON is structured, and the model is less likely to be rewritten without authorization). Each sessiononly works on one feature, completes it, tests it, submits it, updates the progress, and then moves on to the next one.

5. Verification: Change "good or bad" into "pass or not"

This is the subsystem with the lowest investment and the highest return, and it is also the most easily ignored.

The model has two fatal tendencies:

1. Premature declaration of victory - Saying "done" without testing.
2. Self-praise - Ask it to evaluate its own output, and it will almost always say "excellent", even if it looks like a mess to others.

Countermeasures:

• Explicitly list the verification commands (test/lint/typecheck) in the document so that the Agent can run it every time.
• For web applications, it is required to use browser automation (such as Puppeteer MCP) for end-to-end verification, rather than "just look right". Anthropic's actual measurement has greatly improved the accuracy of "the function is really usable".
• Turn subjective qualityinto an objective standard that can be scored. When Anthropic does front-end work, it splits the subjective judgment of "good or bad" into four evaluable dimensions: design quality, originality, craft, and functionality, and then uses few-shot examples to calibrate reviewers.

4. Advanced methods for long tasks

For short tasks, it is enough to do the above five things well. But when the task needs to run for several hours and span dozens of context window, three advanced modes are needed.

1. Separate initializing Agent and executing Agent

Anthropic's long-term task harness is a dual-role architecture:

• Initializer Agent: The first session lays the foundation - write init.sh, build a progress file, make the first git commit, and generate the 200+ feature list.
• Coding Agent (Execution): Each subsequent session follows a fixed process - read the progress → run the E2E smoke test first → complete a feature → submit → update the progress, must leave a clean state that can be merged when leaving.

2. Separation of generation and evaluation (Generator/Evaluator)

Don't let the same Agent be both a player and a referee. Independent Generators and Evaluators can crack "self-praise". The evaluator only pays for it when the task is beyond the scope of "a single model can reliably complete it alone" - when the task is simple, this set of overhead is a waste.

Anthropic's classic controlled experiment: one sentence prompt makes a retro game.

• Single Agent running alone (solo run): $9, 20 minutes, producing an application that cannot run.
• Three Agent harness (planning + generation + evaluation): $200, 6 hours, to produce a playable game with exquisite UI.

The quality gap can support this investment - the premise is that the task is really difficult.

3. Context reset is better than context compression

When the model feels that "the token is about to run out", context anxiety will occur - ending in a hurry. The intuitive approach is to compress the history into a new window; but Anthropic found that it is better to directly clear the context and start over with a structured handover product (progress file + feature list). This also echoes what LangChain said "Ralph Loop": re-inject prompt in a clean new window to combat context rot (context rot).

5. In-depth reading of the case: How did OpenAI sustain its 1 million lines of code?

OpenAI's "Harness Engineering: Leveraging Codex in an Agent-First World" is currently the most detailed practical record. Taking it apart, almost every piece of experience can be mapped back to the previous five subsystems - but there are a few points that are counter-intuitive enough and worth talking about separately.

1. The role of engineers has changed: don’t write code, build the environment

Early progress was slower than expected. The reason was not that the Codex was not good, but that the environment lacked specifications—the Agent lacked tools, abstractions, and internal structures. So the core work of engineers becomes one sentence: "What capabilities are missing, and how to make them visible and mandatory to the Agent?"

When something goes wrong, the fix is ​​almost never "make the model work harder" but go back and fix the harness. Humans only work at higher levels of abstraction: prioritizing, translating user feedback into acceptance criteria, and validating results. Even the repairs are done by Codex itself.

2. Give a map, not a thousand-page manual

They also tried "a big AGENTS.md" at first, and it failed very typically:

• Context is a scarce resource - large files crowd out tasks, code, and related documents;
• All focus = no focus - Agent degenerates into partial pattern matching;
• Instant rot - quickly filled with expired rules and left unmaintained;
• Difficult to verify - A large file cannot be mechanically checked (coverage, freshness, cross-linking).

Change the method: Treat AGENTS.md as a table of contents, not an encyclopedia. An AGENTS.md of about 100 lines is just a "map", and the real sources of truth are placed in the structured docs/ directory - design documents, execution plans (active/completed/technical debt tracking), generated DB schema, product specifications, *-llms.txt references, etc. Plans are first-class citizens: Use temporary lightweight plans for small changes, and execute plans signed into the warehouse after completion of complex work, with progress and decision logs.

This is Progressive Disclosure: Agent enters from a small but stable entrance and is "taught" where to find the next step. Moreover, mechanical enforcement - specialized linter and CI verify whether the knowledge base is up to date and cross-linked; there is also a "doc-gardening" Agent that regularly scans expired documents and automatically proposes repair PRs.

3. The most important thing to remember: If the Agent cannot be seen, it does not exist.

From the agent's point of view, anything it can't access in-context while running effectively doesn't exist.

That Slack discussion that aligned the team structure? If the Agent cannot retrieve it, it is the same as "newcomers joining the company three months later don't know" and it does not exist. Conclusion: Continuously stuff context into the warehouse - code, markdown, schema, executable plan, these are the only things that the Agent can see.

This leads to a set of counter-intuitive trade-offs: Prefer dependencies and abstractions that the Agent can fully internalize. The so-called "boring" technologies are better modeled because their APIs are stable, composable, and appear frequently in the training set. Sometimes it is more cost-effective to rewrite a subset yourself than to bypass an opaque upstream library. Instead of using the universal p-limit, they hand-write a map-with-concurrency, deeply integrating their own OpenTelemetry, 100% coverage, and fully controllable behavior.

4. Make the application itself readable by the Agent (this is a real bottleneck in throughput)

After the code throughput increases, the bottleneck becomes human QA capabilities. The countermeasure is to make the UI, logs, and indicators directly visible to Codex:

• Each git worktree can independently start an application instance, one instance is allocated for each change;
• Chrome DevTools Protocol is connected to the Agent runtime, and DOM snapshots, screenshots, and navigation skills are created - Codex can reproduce bugs, verify repairs, and reason about UI behavior by itself;
• Each worktree is equipped with a temporary observability stack, and Codex uses LogQL to check logs and PromQL to check indicators. So "Guarantee that the service startup is completed within 800ms" and "There is no span in these four critical links for more than 2 seconds" This kind of prompt becomes executable.

Effect: A single Codex run often lasts for more than 6 hours (usually while the person is sleeping).

5. Enforce invariants, not micromanage

Documentation cannot support the coherence of a fully automatically generated code base, only architectural constraints can. Their slogan is "enforce invariants, not micromanage implementations":

• It requires "Resolve data shape at the boundary", but does not specify how to do it (the model itself likes to use Zod, no one specifies it);
• The entire application is built on a rigid layered architecture: each business domain has a fixed layer (Types → Config → Repo → Service → Runtime → UI), the dependency direction is strictly verified, and cross-cutting concerns (authentication, connectors, telemetry, feature switches) can only be entered from a single Providers interface;
• All use custom linter (also written in Codex, of course) and structured testing mechanical force; customize the error message of lintand directly inject repair guidance into the Agent context.

A highlight: **This kind of architecture was originally needed by hundreds of engineers in the company; with Agent, it became a prerequisite from the beginning - constraints are the prerequisite for "fast but not out of order". ** The principle is "The center enforces boundaries, and local autonomy is allowed": Strictly maintain boundaries, correctness, and reproducibility; within the boundaries, give the Agent full freedom. Code does not always conform to human aesthetics. As long as it is correct, maintainable, and readable by future Agents, it will meet the standard.

6. Throughput changes the merge philosophy

When the Agent throughput far exceeds the attention span of a human being, many traditional engineering specifications are harmful: the warehouse has almost no blocking merge access control, PR is short-lived, and test flake is solved with "rerun once" instead of blocking indefinitely. Because in this kind of system, correction is very cheap and waiting is expensive. - This is irresponsible in a low-throughput environment, but it is often true here.

Going deeper, behind this is the economic core of the entire engineering practice: tokens, computing power, and Agent working hours are no longer scarce. The only thing that is truly scarce is the attention that "requires simultaneous intervention." ** So almost all engineering decisions converge to the same goal - **to save people's simultaneous attention to the extreme. The trade-offs of merging access control, cracking QA bottlenecks, and automatic background cleaning are all essentially saving this item. Once you understand this, all the previous counterintuitive choices will become logical.

7. Entropy and garbage collection: "encoding people's taste once and forcing it permanently"

Fully automatic also brings new problems: Codex will copy the existing patterns in the warehouse, including bad, so it will inevitably drift.

They initially relied on manual cleaning - Every Friday (20% of working hours) was dedicated to cleaning "AI slop", without scaling at all. The real solution is to encode the golden principles into the warehouse and equip it with a periodic cleaning process:

• Prioritize using shared toolkit to converge the invariants in one place instead of hand-writing scattered helpers everywhere;
• Not "YOLO-style" geophysical data - but check at the boundary or use a typed SDK to prevent the Agent from being built on the guessed data shape;
• A set of background Codex tasks regularly scan for deviations, update quality scores, and propose directional refactoring PRs - most of which can be reviewed within one minute and automatically merged.

This mechanism is like garbage collection. Technical debt is a high-interest loan: it is always better to continue to repay it in small amounts than to let it compound and repay it in painful clusters. Human taste only needs to be captured once and then continuously enforced on every line of code.

8. The tipping point of autonomy

As testing, verification, review, feedback processing, and recovery are all coded into the system, this warehouse has recently crossed a threshold: given a prompt, Codex can verify the current status end-to-end → reproduce the bug → record a video of the failure → implement the repair → drive application verification → record a video of the repair → open a PR → respond to feedback from people and agents → detect and fix build failures → Only upgrade to people when judgment is needed → Merge.

But they clearly reminded: This is highly dependent on the specific structure and tool investment of the warehouse. Don't assume that it can be directly generalized - at least not yet.

In one sentence: human discipline has not disappeared; it has moved from the code itself into the harness.

6. Comparing approaches: how far should you go?

According to the investment, it is divided into three levels from light to heavy:

• A. Naked prompt - only give a README and add nothing.
• B. Single Agent + Five Subsystems - Complete the five items in Section 3; one Agent can span sessions.
• C. Multi-Agent complete set - Layer the advanced methods of Section 4 on top of B (initialization/execution separation, generation/evaluation separation, context reset).

How to choose depends on a question: Can an Agent complete this task in one session?

• Yes, and throw it away → A
• To continuously iterate and span multiple sessions → B (in most cases)
• An Agent cannot handle it alone (several hours, spanning dozens of windows, high quality requirements) → C

In summary:

• The optimal solution for most teams is B - the highest input-output ratio and the best cost-effectiveness point. Don’t overlay multiple Agents as soon as you start.
• C is only cost-effective when the task is "beyond the capabilities of a single model alone": more than a few hours, spanning multiple windows, and with high quality requirements (such as complete applications, complex reconstructions). Its overall rating is not higher than B because the set of overhead in simple tasks is purely wasteful - the complexity must match the difficulty of the task.
• A For one-time, disposable exploration only. Anything that requires continuous iteration, stopping at A will pay the price of repeated rework.

A discipline that has been proven repeatedly: After the model is upgraded, go back and perform ablation testing on the harness piece by piece. ** Anthropic discovered on Opus 4.6 that after the model becomes stronger, the original "sprint contract" mechanism can be deleted entirely without a drop in quality and a significant drop in tokens. **Harness does not just increase but does not decrease - as the model adds capabilities, the burden on the harness should be reduced.

7. Ready-to-use harness checklist

When you land, check this list:

• Instructions
  • There is a AGENTS.md / CLAUDE.md with ≤100 lines. Write down the project, technology stack, first run command, and red line constraints.
  • Follow the links for details, don’t pile them up into an encyclopedia.
  • Everything the Agent needs is in the repository (repo = single source of truth)
• Tools / Environment
  • Dependencies, runtime versions, and container configurations are complete, and the environment can be started with one click (init.sh)
  • Provides a sandbox that can run bash/execute code
  • Permissions should be granted based on the least privileges, rather than banning them across the board.
• State
  • There is a progress file to record "finished/in progress/stuck"
  • Reading progress + git log at the beginning of the session, updated before the end
  • Use git to commit and leave traces
• Scope
  • Split the task into a machine-readable feature list (JSON is recommended)
  • Only do one feature per session
• Verification
  • The test / lint / typecheck commands are explicitly listed in the documentation.
  • Web applications have end-to-end validation (browser automation)
  • Subjective quality has been broken down into objective dimensions that can be scored
• Long mission extras
  • Separation of initialization and execution of Agent
  • Separation of generation and evaluation (only if the task is difficult enough)
  • Use context reset + handover products instead of blind compression

8. Why this matter will be important in the long run

Some people may ask: Isn’t the model getting stronger and stronger? When it is smart enough, won’t the harness be useless?

Quite the opposite. The judgments of LangChain and OpenAI are consistent: the stronger the model, the focus of harness is just shifting from "patch-filling the pits of the model" to "optimizing the system for intelligence" - but it will not disappear. Just as models are no longer stupid today, prompt engineering is still important.

There is also a layer of harder coupling that is often overlooked: Today's strong models are trained together with the harness. LangChain pointed out that products such as Claude Code put "model + harness" into the same loop for joint debugging in the post-training stage, and the model is specially optimized to fit the shell it was trained in. This also explains a counter-intuitive phenomenon - putting a strong model into an unfamiliar harness often fails to achieve its true level. The relationship between model and harness is co-evolution, not that one will replace the other sooner or later.

OpenAI’s words pointed out the industry’s turn:

In the agent-first world, the engineer's main job is no longer to write code, but to design an environment that allows the Agent to produce reliable output.

The model is the engine, and the harness is the chassis, transmission and instrument panel. With just an engine, it can't run far and it's not safe.

References

• LangChain — The Anatomy of an Agent Harness: Component panorama of Agent = Model + Harness.
• Anthropic — Effective harnesses for long-running agents: Actual implementation of initializing Agent, feature list, and self-verification.
• Anthropic — Harness design for long-running apps: Generation/evaluation separation, context reset, scoreable quality.
• OpenAI — Harness Engineering: Leveraging Codex in an Agent-First World: One million lines of code and the golden rule.
• WalkingLabs — learn-harness-engineering (Online Handouts): 12 lectures + 6 hands-on projects systems course (source of the Five Subsystems Framework).
• WalkingLabs — awesome-harness-engineering: Collection of resources (Context, Assessment, Guardrails, Orchestration, Benchmark).

An introductory guide for engineers and technical decision-makers. From concepts to practice, with Python SDK examples.

1. Why MCP?

Before MCP, wiring an AI application to external systems looked roughly like this:

• Want the model to query a database? Write a function calling schema, write a handler, write permission checks.
• Want the model to read files? Do it all again.
• The same "look up a GitHub Issue" capability — Claude Desktop, Cursor, VS Code, your own Agent — each implements it separately.
• As tools accumulate, prompt-maintenance cost grows fast, and cross-application reuse is effectively zero.

This is the classic M × N integration problem: M AI applications × N data sources/tools = M × N integration codebases.

MCP (Model Context Protocol) is an open protocol led by Anthropic that has become the de facto standard. Its goal is to collapse M × N into M + N:

• Data-source/tool vendors only need to implement an MCP Server once;
• AI applications only need to implement an MCP Client once;
• Any Client can plug into any Server.

The official one-liner: MCP is to AI applications what USB-C is to electronics — a single, unified interface that connects everything.

2. The Big Picture in One Diagram

                          ┌─ Tools       (model-controlled, side effects)
              Server ─────┼─ Resources   (application-controlled, read-only context)
             /            └─ Prompts     (user-controlled, workflow templates)
            /
        Client
       /
  Host
       \                  ┌─ Sampling    (Server asks LLM in reverse)
        Client ───────────┼─ Elicitation (Server asks user in reverse)
             \            ├─ Roots       (Client tells Server its working directories)
              \           └─ Logging     (Server emits logs)
               Server

         Data layer:      JSON-RPC 2.0
         Transport layer: stdio (local) / Streamable HTTP (remote, OAuth supported)

• Transport layer: Client and Server speak JSON-RPC 2.0, carried over stdio or Streamable HTTP.
• Server primitives: capabilities Server actively exposes to the Host, targeting three different "decision-makers" — the model (Tools), the application (Resources), and the user (Prompts).
• Client primitives: capabilities Client exposes for Server to call back, letting the Server complete agentic workflows without depending directly on an LLM/UI itself.

3. The Three Most Confusable Roles: Host / Client / Server

This is the easiest place for newcomers to get tangled up. The relationship looks like this:

Notice that Server C in the lower right is connected to two Clients at once — a remote Server typically serves multiple Clients, while a local stdio Server is usually 1:1.

A common misconception: that a "Server" must be a remote service. Wrong. Server is a protocol role, not a deployment shape. A local subprocess launched over stdio is just as much a Server.

4. The Two Layers of the Protocol: Data + Transport

MCP's design cleanly separates two layers so they can be reused in different scenarios.

1. Data Layer

Built on JSON-RPC 2.0, defining message structure and semantics. It includes:

• Lifecycle management: connection setup, capability negotiation, connection teardown
• Server capabilities: tools, resources, prompts
• Client capabilities: sampling, elicitation, logging, roots
• Notification mechanism: list changes, progress updates, etc.

2. Transport Layer

Responsible for shuttling data-layer JSON messages between the two ends. MCP currently defines two official transports:

Older versions of the protocol had a separate SSE transport, but the new spec folds it into Streamable HTTP. For new code, just pick Streamable HTTP.

5. The Three Server Primitives: Tools / Resources / Prompts

This is the part you'll touch most often in day-to-day development. The three are easy to confuse, but their design intent is completely different — the key distinction is "who decides to invoke them".

I like to remember it as:

Tools are verbs, Resources are nouns, Prompts are workflows.

Tools: invoked by the model

# Hearing the user say "check the weather in San Francisco", the model decides to call this tool itself
@mcp.tool()
def get_weather(city: str) -> str:
    """Get the current weather for a city"""
    return fetch_weather_api(city)

Related methods: tools/list (discovery), tools/call (execution).

Resources: read on demand by the application

# The application decides whether to feed this README to the model as context
@mcp.resource("file:///{path}")
def read_file(path: str) -> str:
    return open(path).read()

Each resource has a URI (e.g. file:///README.md, postgres://mydb/schema) and supports templating (weather://forecast/{city}). Related methods: resources/list, resources/templates/list, resources/read, resources/subscribe.

Tools vs Resources: full data flow and how to choose

Looking only at "who controls it" isn't intuitive enough. Compare the full data flow of the two:

Tools flow (triggered within a model turn):

1. Host starts up → calls tools/list to get schemas
2. Host injects schemas into the tools field of the LLM call
3. User sends a message → LLM reasons → emits a tool_use block
4. Host intercepts → routes to the right Server → sends tools/call
5. Server executes (runs SQL, hits an API) → returns content
6. Host stitches content back into the conversation as tool_result
7. LLM continues generating (may trigger another round, looping 3-6)

Resources flow (injected outside the conversation turn):

1. Host starts up → calls resources/list and resources/templates/list
2. Host surfaces resources in the UI (file tree / @ completion / auto-suggestion)
3. Three ways a resource enters conversation context:
   a. User manually @-references it
   b. Application heuristically injects it
   c. Bridged as a Tool so the model can invoke it (detailed below)
4. Host calls resources/read(uri) → Server returns contents
5. Host attaches contents as part of a user message to the LLM
6. By the time the LLM sees it, it's already "in the context" as a fact

One-line distinction:

Tools are pulled by the model during an LLM turn; Resources are pushed by the application outside an LLM turn.

"Data, but requires computation" — which should I pick? Decision order:

1. Side effects? Yes → must be a Tool (even if just for telemetry).
2. Want the model to decide autonomously? → Tool.
3. Want the user/application to preselect what gets pushed as context? → Resource Template.
4. Client ecosystem considerations: today, Tools are supported in every Host, while UI support for Resources varies a lot. Many Servers expose the same capability as both a Tool and a Resource — Tool for fallback compatibility, Resource for a more elegant presentation on Hosts that support it.

Can Resources also be driven by the LLM? The protocol layer doesn't forbid it — "application-controlled" is design intent, not a technical constraint. The common pattern is Resource-as-Tool bridging: the Host injects two synthetic tools into the LLM's tool list:

{ "name": "list_resources", "description": "List all available MCP resources", ... }
{ "name": "read_resource",  "description": "Read a resource by URI",         ... }

The LLM decides to call read_resource(uri="postgres://schema/users") → the Host forwards it as resources/read. The form is a Tool, but the essence is the LLM driving a Resource. Claude Code does this by default.

What exactly is "application heuristic injection"? A few real-world scenarios:

• Context injection in IDE-style Hosts: every message automatically includes the file currently under the cursor, the few most recently edited files, and convention files like .cursorrules / CLAUDE.md.
• Project-open auto-loading: when a project is opened, automatically read README.md, package.json, .env.example as system context.
• Semantic search auto-recall: embed the user message, vector-search across all resources, automatically splice in the Top-K hits.
• Subscription-based live sync: user edits a file → Server pushes notifications/resources/updated → Host refreshes the new content into the next turn of context.

None of these require explicit initiation from user or model; the Host decides via its own ruleset.

Prompts: explicitly user-triggered

@mcp.prompt()
def plan_vacation(destination: str, days: int) -> str:
    """Generate a vacation plan"""
    return f"Please help me plan a {days}-day trip to {destination}..."

In applications like Claude Desktop, Claude Code, and Cursor, Prompts typically surface as / commands or shortcuts in a command palette.

Three commonly confused points about Prompts deserve clarification:

1. "User-only triggering" is a UX convention, not a protocol law. The protocol layer doesn't restrict who calls prompts/get — any party with a session can. "user-controlled" is a UX recommendation given to Hosts in the spec, intended to make users feel that they are actively initiating the action and to discourage models from silently invoking templates. A custom Agent can absolutely prompts/get automatically at a workflow node — technically nothing stops it.

2. The return value is not just a string. What prompts/get actually returns is a messages array:

{
  "messages": [
    { "role": "user",      "content": { "type": "text",  "text": "..." } },
    { "role": "assistant", "content": { "type": "text",  "text": "..." } },
    { "role": "user",      "content": { "type": "image", "data": "base64...", "mimeType": "image/png" } },
    { "role": "user",      "content": { "type": "resource", "resource": { "uri": "...", "text": "..." } } }
  ]
}

You can construct multi-turn few-shot examples, multimodal prompts containing images/audio, or embedded resource references. In FastMCP, having @mcp.prompt() return a string is just a convenience wrapper — it gets auto-wrapped into a single user message. For richer structures, explicitly return list[Message]:

from mcp.server.fastmcp.prompts import base

@mcp.prompt()
def debug_session(error: str) -> list[base.Message]:
    return [
        base.UserMessage("I ran into this error:"),
        base.UserMessage(error),
        base.AssistantMessage("Let me help analyze. First, a few clarifying questions..."),
    ]

3. Prompts ≠ a lightweight version of Skills. These two are often conflated, but they solve completely different problems:

A more accurate analogy:

Prompts are like IDE Code Snippets or Notion Templates: user selects → template gets filled in. Skills are like Unix man pages + executable scripts: the model reads the manual → decides whether to use it → may also execute the embedded code.

In a sentence: Prompts are "templates the user can use"; Skills are "capabilities the model can learn".

6. Client Primitives: Letting the Server "Call" the Client Back

The Server isn't just a passive responder — it can also actively request capabilities from the Client. There are four client primitives:

Why Sampling is elegant: the Server wants to use an LLM but doesn't want to pay for one or be locked to a specific provider, so it reverse-delegates "calling the LLM" to the Client. The Client already has LLM access (the user has paid for/authorized it), so the Client bears the cost and effort, and the user can audit both the prompt and the response in the middle — this is human-in-the-loop by design.

7. Lifecycle: A Full Handshake

With roles and primitives in mind, let's walk through a minimal complete JSON-RPC flow — useful for the next time you need to debug with packet captures.

Step 1. Initialization handshake

// Client → Server
{
  "jsonrpc": "2.0", "id": 1, "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "elicitation": {} },
    "clientInfo": { "name": "example-client", "version": "1.0.0" }
  }
}

// Server → Client
{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": { "listChanged": true },
      "resources": {}
    },
    "serverInfo": { "name": "example-server", "version": "1.0.0" }
  }
}

// Client → Server (notification — no id, no return value)
{ "jsonrpc": "2.0", "method": "notifications/initialized" }

A few key points here:

1. Protocol version negotiation: both sides must use compatible versions, otherwise the connection terminates.
2. Capability declarations: the Server explicitly lists the primitives it supports under capabilities — in this example only tools and resources are declared, meaning the Server doesn't support prompts and the Client won't issue any prompts/* calls. A server that declares tools.listChanged: true will proactively send notifications/tools/list_changed whenever its tool list changes.
3. {} is not an empty object: it means "I support this capability, with no configurable options" — the minimal form of a declaration.

Step 2. Discover tools

// Client → Server
{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }

Step 3. Invoke a tool

// Client → Server
{
  "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": {
    "name": "weather_current",
    "arguments": { "location": "San Francisco", "units": "imperial" }
  }
}

Step 4. Server-initiated notification

// Server → Client (tool list changed — no response needed)
{ "jsonrpc": "2.0", "method": "notifications/tools/list_changed" }

8. Hands-On with the Python SDK

The rest uses the official Python SDK (mcp) throughout.

1. Install

uv is recommended:

uv init mcp-demo
cd mcp-demo
uv add "mcp[cli]"

Or with pip:

pip install "mcp[cli]"

2. A minimal Server: Tools + Resources + Prompts all together

server.py:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Demo")

# ---- Tool: invoked by the model; has side effects ----
@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

# ---- Resource: read on demand by the application ----
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """Generate a personalized greeting based on name"""
    return f"Hello, {name}!"

# ---- Prompt: explicitly user-triggered ----
@mcp.prompt()
def greet_user(name: str, style: str = "friendly") -> str:
    """Generate a greeting prompt template in different styles"""
    styles = {
        "friendly": "Please write a warm, friendly greeting",
        "formal":   "Please write a formal greeting",
        "casual":   "Please write a casual, easygoing greeting",
    }
    return f"{styles[style]}, addressed to a person named {name}."

if __name__ == "__main__":
    mcp.run()  # stdio transport by default

Three ways to launch:

# Debug: MCP Inspector provides a web UI
uv run mcp dev server.py

# Install into Claude Desktop
uv run mcp install server.py

# Switch to HTTP transport (recommended for production)
# In code, change to mcp.run(transport="streamable-http")

3. Structured output: auto-generate schemas with Pydantic

FastMCP auto-derives JSON Schema from type annotations, making return data easier for the model to understand:

from pydantic import BaseModel, Field
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Weather")

class WeatherData(BaseModel):
    temperature: float = Field(description="degrees Celsius")
    humidity: float = Field(description="percent")
    condition: str = Field(description="weather condition, e.g. sunny / cloudy")

@mcp.tool()
def get_weather(city: str) -> WeatherData:
    """Get weather for a city (structured return)"""
    return WeatherData(temperature=22.5, humidity=45.0, condition="sunny")

4. Context injection: logging, progress, Sampling, Elicitation

Add a Context parameter to a tool and FastMCP will auto-inject it. With it you can do logging, progress reporting, reverse LLM calls, and prompting the user for input:

from mcp.server.fastmcp import Context, FastMCP
from mcp.types import SamplingMessage, TextContent

mcp = FastMCP("Advanced")

# Progress reporting + logging
@mcp.tool()
async def long_task(name: str, ctx: Context, steps: int = 5) -> str:
    await ctx.info(f"Starting task: {name}")
    for i in range(steps):
        await ctx.report_progress(
            progress=(i + 1) / steps,
            total=1.0,
            message=f"step {i+1}/{steps}",
        )
    return f"Task {name} done"

# Sampling: ask the Client's LLM in reverse
@mcp.tool()
async def summarize(topic: str, ctx: Context) -> str:
    """Have the Host's LLM summarize for me"""
    result = await ctx.session.create_message(
        messages=[
            SamplingMessage(
                role="user",
                content=TextContent(type="text", text=f"Summarize {topic} in one sentence"),
            )
        ],
        max_tokens=100,
    )
    return result.content.text if result.content.type == "text" else str(result.content)

5. Lifecycle management: set up connections on startup, clean up on shutdown

When you need to initialize long-lived resources like database connection pools at startup, use lifespan:

from dataclasses import dataclass
from contextlib import asynccontextmanager
from mcp.server.fastmcp import Context, FastMCP

@dataclass
class AppContext:
    db: "Database"

@asynccontextmanager
async def app_lifespan(server: FastMCP):
    db = await Database.connect()
    try:
        yield AppContext(db=db)
    finally:
        await db.close()

mcp = FastMCP("MyApp", lifespan=app_lifespan)

@mcp.tool()
def query(sql: str, ctx: Context) -> str:
    app_ctx: AppContext = ctx.request_context.lifespan_context
    return app_ctx.db.execute(sql)

6. Client: stdio connection to a local Server

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    params = StdioServerParameters(
        command="uv",
        args=["run", "server.py"],
    )
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            tools = await session.list_tools()
            print("Tools:", [t.name for t in tools.tools])

            result = await session.call_tool("add", arguments={"a": 5, "b": 3})
            print("Result:", result.content[0].text)

asyncio.run(main())

7. Client: Streamable HTTP connection to a remote Server

import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    async with streamablehttp_client("http://localhost:8000/mcp") as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print("Tools:", [t.name for t in tools.tools])

asyncio.run(main())

9. Concrete Mapping in Claude Code

Theory done — let's see what the three primitives actually look like inside a real Host. Using Claude Code as the example:

Tools → mcp__<server>__<tool> tools

Each Server's tools are renamed and injected into the model's tool list. For example, with the github MCP server installed, the model sees a tool called mcp__github__create_issue.

A noteworthy mechanism is Tool Search (on by default): tool definitions are not stuffed into the context window all at once — the model first sees a ToolSearch tool and looks up tools on demand. So even with 20 Servers installed, the context window doesn't blow up. You can use alwaysLoad: true to force frequently used Servers to stay resident.

Resources → @ references + bridged Tools, both at once

Claude Code's support for Resources is a textbook illustration of the previous section — application-driven and model-driven exist side by side:

Path A: user-initiated @ reference

Can you analyze @github:issue://123 and suggest a fix?
Compare @postgres:schema://users with @docs:file://database/user-model

Typing @ triggers autocomplete, listing available resources from all connected Servers, with fuzzy search. The referenced resource is pulled into the context as an attachment.

Path B: model-initiated invocation (bridged as Tool)

From the official docs:

"Claude Code automatically provides tools to list and read MCP resources when servers support them"

Claude Code automatically wraps resources/list and resources/read as built-in tools exposed to the model — so the model can decide on its own whether to look up resources.

Prompts → /mcp__<server>__<prompt> slash commands

Each Server-defined prompt maps to a slash command:

/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug in login flow" high

• Arguments are parsed according to the prompt's schema, space-separated;
• Spaces in server and prompt names are normalized to underscores;
• The messages array returned by a prompt is spliced directly into the conversation.

Support status for client primitives

• Elicitation: pops an interactive dialog (form mode or URL mode); hooks can auto-respond.
• Roots: at Server startup, the CLAUDE_PROJECT_DIR environment variable is set; the Server can also call roots/list to query the current working directory.

Takeaways for Server authors

Different clients vary widely in their support for MCP primitives. If you want your Server to maximize compatibility:

• Tools support is mandatory — this is currently the greatest common denominator across all MCP clients.
• Expose important capabilities twice: write a Tool as the fallback, and also a Resource Template so Hosts that support it can present it more elegantly. For a lookup, for example, provide both a query_user(id) Tool and a user://{id} Resource Template.
• Prompts are a nice-to-have: for Hosts that support Prompts, they noticeably improve the UX for common workflows.

10. MCP vs Function Calling vs Custom Plugin Protocols

This is one of the most common questions in internal tech talks.

A rough decision rule:

• Capability serves a single AI app and is essentially never reused → Function Calling is enough.
• Capability will be consumed by multiple AI apps (multiple internal products + third-party tools like Claude Desktop / Cursor) → prefer MCP.
• You need to expose resources and workflow templates to users/models, not just functions → MCP's Resources / Prompts are what Function Calling doesn't have.

11. When Not to Use MCP

Every recommendation has a counter-example. In these situations, forcing MCP only adds complexity:

1. Pure prompt engineering: no interaction with external systems, purely prompt tuning — you don't need MCP.
2. Latency-critical, same-process calls: even with stdio, MCP incurs JSON-RPC serialization overhead; for latency-sensitive scenarios a direct function call is cheaper.
3. Capability tightly coupled to the application and never reused: rolling your own function calling is lighter.
4. General-purpose cross-language, cross-process RPC: that's not MCP's goal — use gRPC / OpenAPI.

12. A Few Tips for Production

When actually deploying MCP, here are a few lessons from stepping on the rakes:

1. Namespace your tool names

Don't call it search; call it github_search_issues or jira_search_tickets. Only then can the model route accurately when several Servers are connected at once.

2. description is written for the model, not for humans

Tool descriptions go directly into the model's context, and wording materially affects invocation accuracy. Be explicit: what it does, when to use it, when not to, and the input constraints.

3. Dangerous operations must use Elicitation

Writing to a DB, sending messages, charging a card — operations with real side effects should proactively call elicitation/create to get user confirmation, rather than trusting that "the model won't go off the rails."

4. Pair Streamable HTTP with OAuth

For remote Servers, stop hardcoding Bearer Tokens in config. OAuth is the auth method recommended by the spec; pair it with roots to scope the Server's working area.

5. Make good use of listChanged notifications

When the tool set changes dynamically with business needs (e.g. a new data source is hooked up), emit notifications/tools/list_changed — the Client refreshes immediately, no restart required.

6. Use the MCP Inspector during development

uv run mcp dev server.py

It spins up a web UI to browse tools/resources/prompts, invoke them manually, and inspect JSON-RPC frames — ten times faster than print-debugging.

13. References

• Official documentation homepage: https://modelcontextprotocol.io/docs/
• Architecture overview: https://modelcontextprotocol.io/docs/learn/architecture
• Server concepts (Tools / Resources / Prompts): https://modelcontextprotocol.io/docs/learn/server-concepts
• Client concepts (Sampling / Elicitation / Roots): https://modelcontextprotocol.io/docs/learn/client-concepts
• Latest specification: https://modelcontextprotocol.io/specification/latest
• Python SDK: https://github.com/modelcontextprotocol/python-sdk
• Official reference Server repository: https://github.com/modelcontextprotocol/servers
• MCP Inspector (a powerful debugging tool): https://github.com/modelcontextprotocol/inspector

Conclusion

MCP debuted in late 2024 and has since gained broad support from major AI applications, including Claude, ChatGPT, VS Code, and Cursor. It is quickly becoming the de facto standard for connecting AI applications to tools and data sources.

Its design philosophy is simple:

Keep the protocol separate from the model. MCP does not dictate how you use an LLM or manage its context. It defines one thing: how AI applications communicate with external systems. And it does so through a clean, general-purpose interface.

For engineers, the payoff of understanding MCP is substantial: build a Server once and any Host in the ecosystem can reuse it; build a Client once and it can connect to any compatible community Server. As the AI application landscape becomes increasingly fragmented, MCP is one of the few protocol layers that preserves engineering value across vendors and products.