A Reading Map of 24 Official Documents for 8 AI Design Patterns

The pit left over from the previous post

In the previous post, I wrote something that "might offend people": Don't fixate on watching one video tutorial after another; go carefully study the official documentation. This is the fastest way to truly master a technology, bar none. Because it is the only material that won't omit boundaries for you just to make the explanation flow smoothly.

At the time I left two to-dos: which official docs to read for each pattern, and how to do acceptance for the patterns. This post delivers on the first one.

Ironically, I only accepted this saying after stumbling myself: in my early years, to rush progress, I built a set of services following a video series. It ran, it went live, and then it crashed inexplicably during a concurrency peak. Later, when I looked through the official documentation, I found that this was stated clearly in two lines in the Limitations section—only those two lines weren't in the video, because the video is only responsible for getting you to run it.

The value of a video is to make you believe this can be done; the value of documentation is to tell you when it will fail. The former gives you confidence, the latter saves your life. 1. First, the method: how to read official documentation 1.1 The value density of documentation is inverted

Most technical documentation has the same structure, and the distribution of value in this structure is completely opposite to how long readers stay.

They won't appear in headings, won't be bolded, and often hide at the very bottom of the page, in a collapsible panel, or behind a politely worded "Note." But they are the real reason that document exists; the places the writers most fear you'll misuse are written right there. 1.2 The four-pass reading method

The order I use myself is different from the document's layout order:

Most people only do pass 1, some do pass 2, almost no one does pass 4, and pass 4 is the only step that can prevent you from crashing in production. 1.3 Three places you must mark

When reading documentation, if you encounter these three kinds of statements, stop immediately and mark them: All MUST / MUST NOT / SHOULD (RFC 2119 semantics). This is not rhetoric. In protocol documents these words have strict definitions; MUST NOT means doing so is wrong, not that it is discouraged. The clause after every "we recommend" / "consider". The wording in official documentation is very restrained. When it finally says "we recommend," the second half of that sentence was usually written only after someone stepped in a pit. For example, Anthropic's sentence "we recommend extensive testing in sandboxed environments, along with the appropriate guardrails" translates to: this thing can get out of control; you must lock it in a cage. Every Error codes table. The error code table is the documentation's "case library." Behind every error code is a type of failure that has actually occurred. Reading the error code table is equivalent to going through all possible pitfalls in advance. II. Overview of 24 primary sources [For reference only; if you have other good materials, feel free to share them in the comments]

The table below is the complete list, for reference only. The "Material Type" column is the classification method I suggest you adopt: concept (C) / interface (A) / boundary (B); none of the three can be omitted.

| # | Pattern | Primary Source | Type | Which Sections to Read First | | --- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ | ---- | ------------------------------------------------------------------- | | 1 | Tool-Augmented | OpenAI Function Calling | C+A | Tool calling flow, toolchoice semantics, Parallel tool calls | | 1 | Tool-Augmented | OpenAI Structured Outputs | A+B | Schema limitations of Strict mode, list of supported/unsupported types | | 1 | Tool-Augmented | MCP Specification | C+B | Annotations in the Tools section (readOnly / destructive / idempotent) | | 2 | ReAct | ReAct paper (arXiv 2210.03629) | C+B | The Limitations section: error accumulation, sparse rewards | | 2 | ReAct | LangChain Agents concepts | C | Its candor about "Agent reliability" | | 2 | ReAct | LangGraph Low Level concepts | A+B | recursionlimit, node termination conditions | | 3 | RAG Agent | LangChain RAG concepts | C | The Retrieval section: query transformation, routing, and when reranking applies | | 3 | RAG Agent | LlamaIndex documentation | C+A | Chunking strategies, Node parser, Response synthesis | | 3 | RAG Agent | Qdrant documentation | A+B | The trade-off between HNSW parameters and recall, and the accuracy loss caused by quantization | | 4 | Memory | LangGraph Memory concepts | C+B | The semantic boundary between short-term and long-term memory, and when to write | | 4 | Memory | LangChain Memory concepts | C | Classification of memory read/write strategies | | 4 | Memory | Redis vector search documentation | A+B | Index types, filter conditions, memory overhead | | 5 | Plan-and-Execute | LangGraph Plan-and-Execute tutorial | C+A | Trigger conditions for re-planning, step granularity | | 5 | Plan-and-Execute | Plan-and-Solve paper (arXiv 2305.04091) | C+B | Comparative experiments with ReAct, failure case analysis | | 5 | Plan-and-Execute | LangGraph How-to guide | A | Subgraphs, branching, state passing | | 6 | Reflection | LangGraph Reflection tutorial | C+A | Structure of the reflection loop, termination criteria | | 6 | Reflection | Reflexion paper (arXiv 2303.11366) | C+B | Case analysis of reflection failures | | 6 | Reflection | Anthropic "Building Effective Agents" | C+B | Prerequisites for applying Evaluator-Optimizer | | 7 | Multi-Agent | LangGraph Multi-Agent concepts | C+A | Handoffs semantics, conditions for applying the four topologies | | 7 | Multi-Agent | Anthropic "Building Effective Agents" | B | When (and when not) to use agents | | 7 | Multi-Agent | Anthropic Multi-Agent Research System | B | Real cost data, coordination overhead | | 8 | Autonomous Loop | LangGraph Persistence concepts | A+B | Checkpoint semantics, Time travel (replay) | | 8 | Autonomous Loop | LangGraph Human-in-the-loop | A+B | interrupt semantics, approval point design | | 8 | Autonomous Loop | OpenAI Agents SDK documentation | A+B | Guardrails and Handoffs, maximum turns | The bolded items are the sections in those documents that are most easily skipped but most valuable. Below, we expand on each one. III. Pattern by Pattern: What to Read · In What Order · Which Sections Are Most Valuable A quick aside: this is my usual learning approach, which I have also mentioned in a previous article: https://cloud.tencent.com/developer/article/2718893 The general reading order is a three-stage process—don't skip steps: 3.1 Tool-Augmented

The three most easily skipped but most valuable sections: The value semantics of tool_choice (auto / required / none / specifying a particular tool). Most people only use the default auto. But the meaning of auto is "the model may choose not to call any tool"—which means your Agent may do nothing in a given turn and then just make up an answer. This is the number one source of bizarre bugs like "the tool was called but had no effect." The Strict mode limitation of Structured Outputs. This section is usually in the lower half of the page: after enabling strict: true, the schema is required to have additionalProperties: false, all fields placed in required, and optional fields written as a union such as ["string", "null"]. Many people get stuck here and then just turn off strict—but what you turn off is not only validation, but also the guarantee that "the model will definitely output according to the schema." The annotations in the MCP Tools section. The MCP specification defines annotations for tools such as readOnlyHint, destructiveHint, and idempotentHint. This is the only place where the protocol layer (rather than you yourself) declares "whether this tool can cause damage." When building permission allowlists and human approval points, you should base them on this, rather than relying on writing "be careful" in your prompt. In one sentence: the hard part of tool augmentation has never been how to call tools, but how to ensure it doesn't call them recklessly. The official documentation devotes far more space to this part than to calling itself. 3.2 ReAct (Reasoning and Acting)

The three most valuable sections: The Limitations section in a paper. The value of a paper lies not in the method, but in the failure modes the authors honestly list: error accumulation caused by the coupling of reasoning and action, hallucination propagation in long chains, and training difficulties under sparse rewards. The cases in your engineering work where things drift off course after running for a while are already described in the paper. LangGraph's recursionlimit. This is a parameter with a very small default value, written in the configuration chapter, and it is easy to mistake it for a performance tuning item. Its true identity is your only guardrail; once ReAct enters a loop, you cannot finish without it. LangChain's candor about Agent reliability. The conceptual documentation explicitly states that Agents are harder to predict, slower, and more expensive than fixed pipelines. When a framework proactively says it does not recommend something, that sentence is worth more than a hundred tutorials. 3.3 RAG Agent (Retrieval-Augmented)

The three most valuable sections: The applicable conditions for Query Transformation. The documentation will tell you about methods such as HyDE, multi-query, and step-back, but the most critical thing is the respective prerequisites for each of them. Many people copy multi-query verbatim, only to retrieve a pile of homogeneous fragments, making the results worse, because the documentation states that it suits scenarios where "the query expression is vague" and does not suit scenarios where "the terminology is precise." The section on Chunking strategies. The section that looks the most boring actually determines the ceiling of your RAG system. The documentation will list the trade-offs among fixed-length, semantic, and document-structure-based splitting, rather than telling you which one is best, because there is no best one to begin with. The explanation of the vector database's HNSW parameters and quantization. Parameters such as efsearch and m, as well as the recall loss caused by quantization (scalar / product quantization). This section directly determines whether your "retrieval accuracy" is 95% or 78%. Most people have never read it, and then blame the model for hallucinations. In one sentence: 90% of RAG problems are not on the generation side, but on the retrieval side. And all the secrets of the retrieval side are in the performance tuning chapter of the vector database documentation, not in any tutorial. 3.4 Memory-Augmented

What to read: LangGraph Memory concepts → LangChain Memory concepts → Redis vector retrieval documentation

The three most valuable sections: The semantic boundary between short-term memory and long-term memory. The LangGraph documentation divides memory into two categories: thread-scoped (relying on checkpoints) and cross-thread (relying on the store). These two categories differ completely in write timing, isolation level, and invalidation strategy. The consequence of mixing them is: User A's preferences appear in User B's conversation. The isolation semantics of threadid. One line of configuration, written in the quick start, that almost no one notices. It is your only data isolation switch. Memory write timing (hot path vs background). The documentation discusses the difference between synchronously writing memory on the main chain and asynchronously writing in the background. This is not just a performance issue: synchronous writes make users perceive latency, while asynchronous writes prevent the current turn from reading what just happened. The documentation explains this clearly, but most tutorials barely mention it. 3.5 Plan-and-Execute

The three most valuable sections: The trigger conditions and upper limit on the number of re-plans. Tutorials will tell you to re-plan when execution fails, but they will not set the limit for you. You must hard-code it yourself. Re-plan without an upper limit = infinite loop + infinite bill. Step granularity. Planning too coarsely is equivalent to no planning; planning too finely means the communication overhead of each step drowns out the benefits. The discussion of task decomposition in the documentation is usually attached to the agentic patterns chapter and is worth reading sentence by sentence. How to pass back subtask failures. This is the engineering detail most easily overlooked in the documentation: when a subtask fails, in what form does the failure information return to the planner? Is it the raw error, or a structured summary? This design determines whether your system can self-repair. 3.6 Reflection

The three most valuable sections: The applicability prerequisites written by Anthropic—this section is the most valuable. The original text has two criteria for judgment: when humans can clearly express feedback, the LLM's output can be significantly improved, and the LLM itself can also provide this feedback. These two criteria are the entry threshold for the reflection pattern. In domains that do not satisfy the first criterion (such as subjective aesthetics or writing without clear standards), adding reflection is simply burning money. The upper limit and termination criteria for reflection rounds. As with re-plan, these must be hard-coded. Moreover, the criterion for when it counts as fixed must be a decidable standard, not the model deciding it is good enough. Failure cases in the Reflexion paper. The paper does not only discuss when the method works well; it also discusses when it does not: reflection can introduce new errors, and without external feedback (such as test results), reflection easily falls into self-confirmation. 3.7 Multi-Agent (multi-agent collaboration)

The three most valuable sections: The Anthropic section "When (and when not) to use agents"—the section most worth copying into your notebook from the entire piece. It explicitly says: if the problem can be solved with a single call + retrieval + in-context examples, do not use an agentic system. This is a rare passage in official documentation that explicitly discourages use. LangGraph's Handoffs semantics: Command(goto=..., graph=Command.PARENT). This navigation mechanism looks like an API detail, but it is actually the fundamental design of "who has the final say" in a multi-agent system. If you cannot understand this section, the multi-agent system you build will inevitably have agents passing the buck to one another. Real cost data for Anthropic's multi-agent research system. The most valuable thing about this engineering blog is the numbers it discloses: the token consumption of a multi-agent system is several times to more than ten times that of an ordinary conversation. This is your best ammunition for persuading others in a solution review meeting. 3.8 Autonomous Loop

The three most valuable sections: Stopping Conditions. Anthropic and various other documentation all emphasize: an autonomous loop must have stopping conditions (maximum number of iterations, timeout, budget cap). This is the only safety device of this pattern, not an optional item. Checkpoint and Time travel (replay). This section determines whether your system can be investigated after something goes wrong. An autonomous loop without checkpoints = an incident that cannot be reproduced. Replayability is a prerequisite for going to production, not a bonus. interrupt and approval points. The Human-in-the-loop documentation is not about "whether humans should participate," but about where in the system to leave a slot for human participation. This section is the direct basis for the design of the Harness layer (see the previous article, L3). In one sentence: all official documentation about autonomous loops reads like a risk disclosure statement. If, after reading it, all you remember is how to keep it running forever, that means you read the wrong part.

--- IV. Five [General Must-Reads] Across Patterns

No matter which patterns you ultimately use, these 5 are recommended to be read in full:

| Material | Why it must be read | Key chapters | | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------- | | Anthropic "Building Effective Agents" | A document from a model vendor that systematically explains when you should not use agents | When (and when not) to use agents / Appendix 2: Prompt Engineering your Tools | | MCP specification | The de facto standard at the protocol layer for tools and context, which determines whether your tool layer can be replaced | Tools / Resources / Sampling / all MUST entries | | LangGraph Low Level concepts | The underlying abstraction of agents from a state machine perspective; once you understand it, you won't fear switching frameworks | Nodes / Edges / State / recursionlimit | | ReAct paper + Reflexion paper | The original sources of the two most important reasoning paradigms, including the failure modes described by the authors themselves | The Limitations / Failure cases chapters of both papers | | OpenAI Agents SDK documentation | A reference implementation that productizes guardrails, handoffs, and tracing | Guardrails / Handoffs / Tracing |

The common takeaway from reading these 5 is: you will start to describe a technology in terms of its boundaries rather than its capabilities. This is the watershed between a user and an architect.

--- V. Reading Plan AI has leveled the technical barrier and raised the value of integration. But for senior technologists, in the end there is only one question: do you want engineering that can be implemented, or a demo?

| Week | Topic | What to Read | Output (must be put on paper) | | ---------- | ---------- | ------------------------------------------------------------------ | ------------------------------------------------------------------- | | Week 1 | Build a worldview | Full text of Anthropic's "Building Effective Agents" + MCP specification Introduction | One page: my definition of an agent, and three criteria for when not to use one | | Week 2 | Connect the utilities | Three Tool-Augmented pieces + three RAG pieces | One table: the value of each parameter → the actual behavior change | | Week 3 | Conquer the reasoning chain | Materials and papers on ReAct + Plan-and-Execute + Reflection | Three failure-mode cards: for each mode, list ≥3 known scenarios that will blow up | | Week 4 | Connect governance | Materials on Memory + Multi-Agent + Autonomous Loop | One checklist: what hard constraints my Harness layer needs (rounds/budget/sandbox/approval/replay) | VI. Self-Check: Did You Really Understand It? 6.1 Quick Reference: Mnemonics for Identifying Three Types of High-Value Chapters

| Category | What it looks like | Typical keywords | The question you must answer | | -------------------------- | ---------------------------- | --------------------------------------------------- | -------------------------------- | | Boundaries | Defines where this capability stops | Scope / Definitions / Overview | What is it not responsible for? | | Limitations | Explicitly lists what it cannot do | Limitations / Constraints / Not supported / Caveats | Which of these limitations will hit my scenario? | | Failure Modes | Describes behavior when things go wrong | Error codes / Troubleshooting / Failure cases | When it fails, does it fail silently or raise an error? |

The third one is the most critical. Silent failure is the biggest enemy of AI systems—the model won't throw an exception; it will just give you an answer that looks perfectly plausible. 6.2 Ten-Point Self-Check

After reading a document, you've only truly read it if you can answer eight of the following ten questions: What is the official definition of this capability? Say it in your own words. What is it explicitly not responsible for? What are its default parameters? Which default value is the most dangerous? When it fails, does it throw an error or silently degrade? What are its error codes? Which is the most common one? Does it guarantee anything about concurrency / idempotency / ordering? What is its cost model? Which operation is the most expensive? Where is its isolation boundary (user / session / tenant)? How many places in the document contain MUST NOT, and what are they? If I need to replace it tomorrow, which code do I need to change?

Item 10 is the replaceability test discussed in the previous article: it is also the best yardstick for testing whether you have truly understood a document. If you can't answer item 10, it means you're only using it, not understanding it. VII. Conclusion

This entire article has been about just one thing: in official documentation, the most valuable content often looks the least like a key point.

And the underlying logic of this matter is the same one I have repeatedly discussed throughout this series: the source of architectural capability is not how many APIs you can call, but whether you clearly know where each API will fail.

So stop asking whether there are any good videos explaining XX. Go read the documentation, read it through a fourth time, until you can memorize the error code table. That is the slowest path, and also the fastest path.