---

🤔 Do any of these sound familiar?

• The AI hands you confident-looking code, it compiles, it looks fine — and then it just doesn't work at runtime
• You ask it to fix the bug; it patches one place and breaks another, and you're stuck in an "AI fixing AI" loop
• You can't tell when to reach for RAG, when to fine-tune, when to just throw more context at the model — everything is trial and error
• Cursor, Claude Code, Copilot, a new agent framework every other week — every new tool feels like learning from scratch again
• Prompt writing feels like superstition: the ones that work, you can't say why; the ones that don't, you can't say why either
• You've read plenty of "AI coding tutorials" — felt like you got it, then a slightly new situation throws you off again

If any of these landed, this book was written for you.

---

🎯 What this book actually does differently

Most AI coding content out there teaches you how to use the tools — how to write prompts, how to configure Cursor, how to call an API.

This book takes a different path:

Every concept here isn't a product feature dropped from the sky — it's a consequence derived, step by step, from underlying principles.

What typical tutorials teach	What this book makes you understand
How to configure the context window	Why the context window exists at all — as a physical constraint of attention's O(n²) cost
How to build an Agent	Why an Agent is the inevitable architecture once tool calling becomes possible
How to implement RAG	Why RAG is an engineering trade-off shaped by the limits of context
How to use the MCP protocol	Why MCP appeared, and what would go wrong without it

Once you understand the why, every new tool, every new concept, every new paradigm becomes a question you can answer:

What problem does it solve? What's the cost? Where does it stop working?

This is an anti-tool-tutorial book. Tools age out. Principles don't.

---

👥 Who this book is for

✅ A good fit if you are:

• An engineer already using AI coding tools, looking to move from "able to use" to "actually good with them"
• A tech lead responsible for choosing AI tooling or designing agent architectures for your team
• A developer who wants to understand the underlying logic behind RAG, Agents, MCP, Skills — not just the surface
• Someone tired of tutorials that go stale every time a tool updates

❌ Probably not a good fit if you are:

• A complete beginner with no programming background (build some real project experience first)
• An ML researcher looking for deep Transformer math (this is an engineering book, not a research one)
• Someone who just wants a copy-paste prompt and calls themselves an "AI user"

---

📖 Read online

🌐 Recommended: Online edition (mkdocs) Full navigation, dark mode, syntax highlighting, and the full set of structural diagrams.

Or click into the table of contents below to jump straight to the Markdown files on GitHub.

---

📚 Table of contents

The book is organized into 4 parts and 15 chapters, along a strictly progressive logical line. Each part is a prerequisite for the next.

📘 Part I — How large language models actually work

Without understanding the model itself, every higher-level discussion floats in the air.

• Chapter 1 — How Large Language Models Actually Work — tokenization, attention, sampling: the full pipeline
• Chapter 2 — What Interaction with an LLM Really Is — context windows, "lost in the middle", and the physical reality of multi-turn dialogue

📗 Part II — From answering to acting

What exactly do you cross when you go from "you ask, it answers" to an Agent that executes tasks on its own?

• Chapter 3 — From Answering to Acting: How Agentic Systems Work
• Chapter 4 — Standardizing Tool Use: How MCP Works
• Chapter 5 — Skill as a Packaged Capability
• Chapter 6 — When One Agent Is Not Enough: Multi-Agent Collaboration
• Chapter 7 — Agent Limits and Failure Modes ⭐

📙 Part III — Memory and context engineering

How does an AI system "remember" you? And why is the token a unit of economics?

• Chapter 8 — Building Memory for AI Systems
• Chapter 9 — Token Economics and the Art of Context Engineering
• Chapter 10 — From RAG to Code-Native Retrieval ⭐

📕 Part IV — Engineering and organization

Individual ability to use AI is one thing. Turning that ability into something an engineering system, a team, and an organization can carry over the long term is another.

• Chapter 11 — From Prompts to OpenSpec: When Requirements Become Engineering Artifacts
• Chapter 12 — Security and Alignment: The Trust Boundary of AI Systems
• Chapter 13 — Rebuilding Judgment: How AI-Written Code Should Be Reviewed
• Chapter 14 — When AI Enters the Team: Reordering Coordination
• Chapter 15 — When AI Enters the Organization: From Tool to Capability Foundation

📎 Appendices

The appendices come in two groups. The essay appendices sit alongside the main fifteen chapters and look at the same shift through three different time scales — the industry, the infrastructure, the engineer's career — plus one underlying reflection on what an LLM actually is. The reference appendices are the practical companions for daily use.

Essay Appendices

• Appendix I — It Is Not a Lesser Human: Notes on What LLMs Actually Are — Turing, Searle, and the conversation the LLM is forcing us to have with ourselves
• Appendix II — Software Ate Only Half the World: From Rule-Based to Token-Based — why the second half of software eats the world runs on a different track
• Appendix III — From API Gateway to AI Gateway: When Infrastructure Is Stretched by Tokens — the new layer of infrastructure non-determinism is forcing into existence
• Appendix IV — The Repriced Engineer: The Second Half of Software Engineering — what the market is marking up, what it is marking down, and how senior gets split into two layers

Reference Appendices

• Appendix A — Quick Reference Cards — fast lookup for key concepts
• Appendix B — A 30-Day Practice Path — an executable plan from beginner to comfortable
• Terminology — glossary of recurring terms

---

💡 A few things that make this book different

1. Every conclusion is derived from prior principles

You won't find sentences like "the industry recommends RAG". You'll find: context windows are limited → so external knowledge has to come from somewhere → there are several retrieval trade-offs → RAG is the optimum under a particular set of constraints.

2. Original structural diagrams throughout

The key mechanisms — attention, the ReAct loop, MCP architecture, layered memory, the knowledge-injection decision tree, and so on — all come with hand-drawn SVG diagrams. Half the understanding comes from looking at the picture.

3. Failure modes get their own real estate

The book doesn't only explain "why you need X" — it also explains "what happens when X is misused". Chapter 7 is dedicated to Agent failure modes, the part most other books quietly skip.

4. A strong sense of where things stop working

Every technique has a boundary. The book is explicit about it: what to use it for, what not to use it for, and where the edge actually is.

5. Built to age slowly

There's no tutorial for any specific tool. Only the underlying principles. Cursor may be replaced tomorrow, but the nature of tokens, attention, context, and Agents won't be.

---

🧰 Companion Skill Pack

The book covers the why. This pack covers the how — it turns the spec-driven workflow of Chapter 11, the review discipline of Chapter 13, and the "one persisted artifact per stage" model into procedures an AI coding tool can load directly.

Skill	Responsibility	Covers
ai-full-lifecycle	Orchestration: determine the current stage, route to sub-skills, manage artifact persistence and handoff across sessions	Entire flow
spec-writing	Templates and acceptance criteria for PRDs, design docs, E2E case docs, and delivery docs	Requirements / design / cases / delivery
ai-coding-discipline	Coding-phase constraints: kickoff checks, ordering, unit-test validity	Coding / test scripts / regression
ai-code-review	Multi-persona review checklists plus the human final-pass focus areas	Review

Install:

git clone https://github.com/caozhiyi/ai-programming-book.git
cd ai-programming-book

cp -r skills/* ~/.codebuddy/skills/                   # user-wide
# or: cp -r skills/* your-project/.codebuddy/skills/  # per-project, shared with the team

See skills/README.md for details.

---

🚀 How to read it

🍱 If you have time (recommended): read it cover to cover

Each chapter naturally raises the question that the next chapter answers. That logical chain itself is the best path through AI coding systems.

⚡ If you're in a hurry: read the part introductions first

Each part opens with a short introduction — what it sets out to solve, what the core takeaway is. Read those first, then decide which chapters to go deep on.

🎯 If you're coming with a question: jump straight in

• Trying to figure out why your Agent fails → go straight to Chapter 7
• Choosing between RAG vs. fine-tuning → go straight to Chapter 10
• Designing an enterprise-grade AI coding system → go straight to Chapter 15
• Building the case for AI adoption to leadership → go straight to Chapter 15

---

🛠️ Local build (optional)

If you'd like to run the mkdocs site locally:

# Install dependencies
pip install -r requirements.txt

# Start the local server (defaults to http://127.0.0.1:8000)
mkdocs serve

# Build the static site
mkdocs build

---

🌟 About the author

I'm caozhiyi, an engineer with a long stretch of years on infrastructure and systems architecture. This book didn't come out of thin air — it grew out of the concrete confusions I ran into while using AI coding tools, and the methodology I distilled from working through them.

I keep writing about:

• Reflections on AI coding from the trenches
• System design and architecture methodology
• Network protocols, QUIC, and other low-level work

📮 Email: [email protected] 🐙 GitHub: @caozhiyi 💬 WeChat Official Account (Chinese): 煮码宝藏

---

🤝 Contribution and feedback

The book is still being polished. Any kind of involvement is welcome:

• 🐛 Found a typo or a technical mistake? → open an Issue
• 💡 Think a derivation could be tightened? → send a PR or open an Issue
• ❓ Got stuck on something? → ask in Discussions
• ⭐ Found it useful? A Star is the best support an author can get.

I read and reply to every Issue.

---

📜 License

This book is released under CC BY-NC-SA 4.0.

In plain words:

• ✅ You can read, copy, and share the content freely
• ✅ You can adapt and build on it (with attribution, and under the same license)
• ❌ No commercial use (no selling it as a printed book, no putting it inside a paid course, etc.)

---