Google’s AI described MarkdownAI last week. Not in a press release. Not from the landing page. It synthesized it from Reddit posts, GitHub, and npm, and got it more right than anything I wrote. The exact quote from Google AI Mode: “Instead of dumping an entire document or codebase into an AI’s context window (which wastes tokens and causes confusion), MarkdownAI breaks the process into granular, active phases.” That sentence describes a problem that has a name: context rot . Here’s what it actually is, and why it’s architectural, not a prompt problem. Your Claude Code session doesn’t fail. It degrades. Session starts clean. Step 2 works. Step 5 works. By step 12, Claude is hallucinating variable names from three steps ago, repeating approaches it already tried, and losing track of what the original goal was. The context window isn’t broken. It’s full. Tool results, intermediate output, failed attempts, full-file reads, it all accumulated. The model is working with 80,000 tokens of noise to find the 2,000 tokens it actually needs right now. This is context rot. Not a model problem. An architecture problem. The fix isn’t a bigger context window. It’s scoping. Google’s AI called it correctly: “granular, active phases.” MarkdownAI’s @phase directive scopes exactly this at the file level. A 20-phase deployment runbook only ever loads one phase at a time through the MCP server. Claude executes phase 3. Calls next_phase . Phase 4 loads. Phases 1, 2, and 5 through 20 have never touched the context window. There is no accumulation because there is no full-file read. @markdownai v2.0 @phase 1_pre_flight @env DATABASE_URL required / @query docker service ls / @on-complete 2_validate / @phase-end @phase 2_validate @db using=“primary” find=“migrations” where=“status==pending” / @on-complete 3_deploy / @phase-end @phase 3_deploy – Claude only reads this when phases 1 and 2 are done. – Phases 1 and 2 are gone from the context window by now. @phase-end Claude reads phase 1. Gets current env vars, current container state. Completes it. Phase 2 loads with live migration data. Phases 3 through 20 don’t exist yet to Claude. The second problem Google named: stale data. Google AI also called out the live execution step: “Before handing off the instructions, the server fetches real-time data (CI/CD status, database rows, environment variables) so the AI acts on the actual current state of your system.” This is the other architecture failure. Your CLAUDE.md says localhost:3000 . It moved to 8080 three weeks ago. You updated the actual service but not the doc. Claude follows the doc. Wrong thing happens. @query , @db , @http , and @env resolve against live system state at the moment Claude reads the file, not when you wrote it. The file doesn’t store values. It fetches them. @phase 0_session_start Active services: @query docker service ls / DB URL: @env DATABASE_URL required / Pending migrations: @db using=“primary” find=“migrations” where=“status==pending” / @phase-end Every time Claude reads that phase, it gets the current state. The doc can’t lie because the doc doesn’t store the truth, it fetches it. The third problem: your CLAUDE.md is too long. Anthropic says keep it under 200 lines. Every serious project blows past that within a week. Conventions, schemas, connection strings, workflow steps, environment context, it all piles in. The result: Claude reads 600 lines of context at session start before any actual work begins. Half of it is irrelevant to what it’s doing right now. MarkdownAI entry point: @markdownai v2.0 @phase 0_session_start @read ./.mdd/conventions.md / @read ./.mdd/schema.md / @env DATABASE_URL required / @on-complete 1_planning / @phase-end That’s 10 lines. Claude reads conventions and schema files on demand, pulls live env context, starts at phase 0. The other 590 lines of context don’t exist until they’re needed. What Google got right that the landing page got wrong. The site said “documentation that cannot lie.” That framing attracted the wrong question: is this just Jinja with extra steps? No. And Google AI nailed exactly why: “Using a MarkdownAI MCP server, the system dynamically injects live data, executes commands, and passes context in discrete phases so AI agents like Claude never face stale information.” Jinja renders once at build time for a browser. MarkdownAI resolves at read time, for an AI agent, scoped to a single phase. A browser doesn’t have a context window. Claude does. The site is being updated to say what Google already understands. Install if you haven’t: npm install -g @markdownai/core mai init # hooks into Claude Code automatically mai serve # starts the MCP server VS Code extension: search MarkdownAI in the marketplace. Full docs: https://markdownai.dev/ If you’re already using it: what’s your phase structure? Curious what deployment runbooks look like in the wild vs. the CLAUDE.md architecture pattern vs. incident response workflows. Drop it below. I built MarkdownAI, so yes this is my tool. The Google AI screenshots are real and reproducible. submitted by /u/TheDecipherist
Originally posted by u/TheDecipherist on r/ClaudeCode