给 AI 喂 HTML 的新逻辑：为何 Claude 弃用 Markdown？
面对长文本带来的模型性能下降，Anthropic 发现 HTML 的语义边界比 Markdown 更能精准引导 AI。通过将核心文档回归代码仓库并利用自动化架构图，开发者可以构建更高效的上下文栈，让 AI 助手不再因信息过载而变笨。
Best quote from 给 AI 喂 HTML 的新逻辑：为何 Claude 弃用 Markdown？
好的文档应该像指令（Directives），而不是描述。能让 AI 理解的代码和文档，通常对人类来说也是最友好的，因为好的逻辑都追求简洁、明确和高信号强度。
Generated by Jiaying
Explain Anthropic's reasoning for preferring HTML over Markdown for LLM contexts (e.g., prompt engineering and context caching). Discuss best practices for internal engineering documentation, specifically comparing repo-based documentation (committing docs alongside code) versus Notion, addressing the user's concerns about Notion's MCP API limitations. Provide a strategy for maintaining a central architectural overview that combines auto-generation from code/metadata with visual diagrams to ensure the AI doesn't have to re-scan the entire codebase for every query.
Frequently Asked Questions
虽然 Markdown 简洁高效，但 HTML 在 AI 交互中具有更强的语义表达能力和结构化优势。HTML 可以携带复杂的元数据、SVG 矢量图、交互式组件以及页面内导航。这使得 AI 不仅能输出文字，还能直接生成带交互功能的 3D 实景地图式的文档，其信息密度和展示维度远超传统的黑白 Markdown 文本。
这主要源于“注意力竞争”和“迷失在中间”（Lost in the Middle）现象。AI 的注意力机制是有限的，当文档中充斥着大量“长得像信号的噪声”时，核心逻辑会被淹没。研究表明，AI 对开头和结尾的信息记忆最准，如果关键约束被埋在几十页文档中间，AI 很容易产生幻觉或忽略重要指令。
上下文栈是一种精准投喂信息的策略，而非将所有文件丢给 AI。它通常分为四层：任务定义、项目背景（技术栈）、任务相关数据（如特定的代码段或接口定义）以及输出格式要求。通过只提供与当前任务直接相关的几千个 token，而不是整个代码库，可以显著提升 AI 的任务成功率并降低 token 消耗。
上下文腐烂是指在长对话中，过时的报错信息、废话和弃用的逻辑堆积，干扰 AI 的判断。解决办法是采用“HANDOFF.md”模式：在一个任务阶段结束时，让 AI 总结当前进度、核心决策和剩余问题，然后开启一个全新的会话窗口，只将这份精简的总结贴入，从而实现“清空缓存”并保留精髓的效果。
将文档与代码“共址”（Co-location）可以确保同步更新，避免文档失效。Notion 等工具在 AI 自动化处理时存在限制，例如不支持原子化的块级操作，AI 修改一个数字可能需要重读重写整个页面。而将文档（如 CLAUDE.md）放在代码仓库根目录，不仅方便 AI 扫描，也能让开发者在修改代码时顺手维护文档，保持高信号强度。
From Columbia University alumni built in San Francisco
"Instead of endless scrolling, I just hit play on BeFreed. It saves me so much time."
"I never knew where to start with nonfiction—BeFreed’s book lists turned into podcasts gave me a clear path."
"Perfect balance between learning and entertainment. Finished ‘Thinking, Fast and Slow’ on my commute this week."
"Crazy how much I learned while walking the dog. BeFreed = small habits → big gains."
"Reading used to feel like a chore. Now it’s just part of my lifestyle."
"Feels effortless compared to reading. I’ve finished 6 books this month already."
"BeFreed turned my guilty doomscrolling into something that feels productive and inspiring."
"BeFreed turned my commute into learning time. 20-min podcasts are perfect for finishing books I never had time for."
"BeFreed replaced my podcast queue. Imagine Spotify for books — that’s it. 🙌"
"It is great for me to learn something from the book without reading it."
"The themed book list podcasts help me connect ideas across authors—like a guided audio journey."
"Makes me feel smarter every time before going to work"
From Columbia University alumni built in San Francisco
"Instead of endless scrolling, I just hit play on BeFreed. It saves me so much time."
"I never knew where to start with nonfiction—BeFreed’s book lists turned into podcasts gave me a clear path."
"Perfect balance between learning and entertainment. Finished ‘Thinking, Fast and Slow’ on my commute this week."
"Crazy how much I learned while walking the dog. BeFreed = small habits → big gains."
"Reading used to feel like a chore. Now it’s just part of my lifestyle."
"Feels effortless compared to reading. I’ve finished 6 books this month already."
"BeFreed turned my guilty doomscrolling into something that feels productive and inspiring."
"BeFreed turned my commute into learning time. 20-min podcasts are perfect for finishing books I never had time for."
"BeFreed replaced my podcast queue. Imagine Spotify for books — that’s it. 🙌"
"It is great for me to learn something from the book without reading it."
"The themed book list podcasts help me connect ideas across authors—like a guided audio journey."
"Makes me feel smarter every time before going to work"
"Instead of endless scrolling, I just hit play on BeFreed. It saves me so much time."
"I never knew where to start with nonfiction—BeFreed’s book lists turned into podcasts gave me a clear path."
"Perfect balance between learning and entertainment. Finished ‘Thinking, Fast and Slow’ on my commute this week."
"Crazy how much I learned while walking the dog. BeFreed = small habits → big gains."
"Reading used to feel like a chore. Now it’s just part of my lifestyle."
"Feels effortless compared to reading. I’ve finished 6 books this month already."
"BeFreed turned my guilty doomscrolling into something that feels productive and inspiring."
"BeFreed turned my commute into learning time. 20-min podcasts are perfect for finishing books I never had time for."
"BeFreed replaced my podcast queue. Imagine Spotify for books — that’s it. 🙌"
"It is great for me to learn something from the book without reading it."
"The themed book list podcasts help me connect ideas across authors—like a guided audio journey."
"Makes me feel smarter every time before going to work"
"Instead of endless scrolling, I just hit play on BeFreed. It saves me so much time."
"I never knew where to start with nonfiction—BeFreed’s book lists turned into podcasts gave me a clear path."
"Perfect balance between learning and entertainment. Finished ‘Thinking, Fast and Slow’ on my commute this week."
"Crazy how much I learned while walking the dog. BeFreed = small habits → big gains."
"Reading used to feel like a chore. Now it’s just part of my lifestyle."
"Feels effortless compared to reading. I’ve finished 6 books this month already."
"BeFreed turned my guilty doomscrolling into something that feels productive and inspiring."
"BeFreed turned my commute into learning time. 20-min podcasts are perfect for finishing books I never had time for."
"BeFreed replaced my podcast queue. Imagine Spotify for books — that’s it. 🙌"
"It is great for me to learn something from the book without reading it."
"The themed book list podcasts help me connect ideas across authors—like a guided audio journey."
"Makes me feel smarter every time before going to work"
![[8d6ac41f-8c3e-4a48-92be-2d60c5c4e626:c0000] Meta Harness.pdf p1-1](/_next/image?url=https%3A%2F%2Fd1y2du6z1jfm9e.cloudfront.net%2Fassets%2Fpodcast%2Fpurple.png&w=1024&q=50)
