{"id":"2066290950352081336","url":"https://x.com/dongxi_nlp/status/2066290950352081336","text":"","author":{"name":"马东锡 NLP","username":"dongxi_nlp","avatarUrl":"https://pbs.twimg.com/profile_images/1955352181453774848/QfD9wuqD_200x200.jpg"},"createdAt":"Sun Jun 14 22:45:27 +0000 2026","engagement":{"replies":16,"retweets":26,"likes":100,"views":92931},"article":{"title":"Markdown Is A Context Interface","previewText":"Harness 系列文章之 5，小小的 markdown 文件，却可以改变 Coding Agent 的世界状态。\n\n.md file works when the harness knows what kind of context it is.\n \n现代 coding agent 里，一个很有意思的现象是：普通","coverImageUrl":"https://pbs.twimg.com/media/HKzoGD_XMAA9OLZ.jpg","content":"Harness 系列文章之 5，小小的 markdown 文件，却可以改变 Coding Agent 的世界状态。\n\n> .md file works when the harness knows what kind of context it is.\n\n![](https://pbs.twimg.com/media/HKzpa5yXMAAABZT.jpg)\n\n现代 coding agent 里，一个很有意思的现象是：普通 markdown 文件可以改变 agent behavior。\n\n加一个 AGENTS.md，Agent 开始遵守 repo-specific rules。\n\n加一个 SKILL.md，Agent 在某类 task 上突然更稳定。\n\nMarkdown file 只是可见部分。\n\n真正有趣的是 Harness 对这种机制的设计：\n\n![](https://pbs.twimg.com/media/HKzpP_PXQAEQjNE.jpg)\n\n## The Naive Markdown Dump\n\n按照习惯，如果我们从一个从 tiny agent 看 markdown：\n\n![](https://pbs.twimg.com/media/HKzpvvpWQAAz8w_.jpg)\n\n这看起来合理，因为 rules，docs，plans，procedures 都经常写在 markdown 里。\n\n但 raw markdown dumping 有代价：\n\n- 旧 notes 会和当前 instructions 竞争\n\n- 长 docs 会挤掉最近的 tool result\n\n- drafts 可能被误当成 rules\n\n- general project guidance 可能盖过 narrow task procedure\n\nModel 得到了更多 text，但 task 得到的有用的 instruction 更少。\n\n所以，\n\n>  .md 应该通过 Harness route 进入 context，不能直接倒进 prompt。\n\n## Two Files, Two Jobs\n\n这里，我们可以一起看两个常用 markdown files，AGENTS.md 以及 SKILLS.md\n\n![](https://pbs.twimg.com/media/HKzqaRaW0AA0wSr.jpg)\n\n它们都是 markdown, 但进入 prompt 的方式不一样。\n\n> AGENTS.md ：In this workspace, behave like this.\n\n> SKILL.md ：For this kind of task, use this procedure.\n\n## Why AGENTS.md Works\n\nAGENTS.md 有效，是因为 Harness 把它当成 workspace instruction context。\n\n它是 project guidance，应该在 model 开始操作 repo 前可见。\n\n例如我自己的 Dongxi Agent 主要任务是要根据每天与 coding agent的交互中，总结学习经验。\n\n那么，在 DongXi 这个 workspace 里，AGENTS.md 要求：做 DongXi Agent 或 coding-agent harness learning 时，要保持 learning artifact current。\n\n这一个文件会改变整个 session 的行为：\n\n![](https://pbs.twimg.com/media/HKzrTkFWsAArvKA.jpg)\n\nModel 仍然负责 writing 和 reasoning。\n\n但 Harness 在 turn 开始前插入了稳定的 project rule。\n\n这就是 AGENTS.md 强的地方：\n\n- 它从 workspace 被发现\n\n- 它被 project 或 directory scope 限定\n\n- 它进入 stable instruction layer\n\n- 它跨多个 tasks 持续生效\n\n- 它让用户不必在每个 prompt 里重复 local conventions\n\n## How AGENTS.md Works\n\n![](https://pbs.twimg.com/media/HKzrkddWQAAS4D0.jpg)\n\n- Harness 应该知道每条 rule 适用于哪个 directory。\n\n- nested workspace 可能有更窄的 rules。\n\n- 这些 rules 应该被当成 instruction context，同时仍然低于 system 和 developer policy。\n\n- 文件内容不应该被盲目复制进每条 visible transcript message。\n\n- 它属于 stable context layer。\n\n这样 prompt 可以保持一致，又不会把 project rules 变成 noisy chat history。\n\n## Where Agents.md Enters The Agent Turn\n\n![](https://pbs.twimg.com/media/HKzu5WaXcAAW5nJ.jpg)\n\nAGENTS.md 在 model turn 组装前加载。\n\n它进入 stable workspace instruction context，和 project rules、local operating constraints 放在一起。transcript 记录发生了什么；AGENTS.md 约束接下来该怎么做。\n\n## Why SKILL.md Works\n\nSKILL.md 有效，原因不同。\n\n它能提升某类 task 的表现，是因为它在正确时机给 model 一个聚焦的 procedure。\n\n没有 skill 时，model 可能懂一般领域，但会漏掉 local workflow。\n\n有 skill 时，Harness 可以提供：\n\n- 什么时候使用这个 workflow\n\n- 哪些 files 或 artifacts 重要\n\n- 哪些 tools 被允许或期待使用\n\n- 应该按什么步骤做\n\n- 什么 checks 证明工作完成\n\n- 用户期待什么 output format\n\n这比一句 vague prompt 强得多：\n\n![](https://pbs.twimg.com/media/HKzr8VfXkAAtjaT.jpg)\n\n这个文件会提升 performance，因为它把 fuzzy ability 变成 repeatable procedure。\n\n## How SKILL.md Works\n\n好的 Harness 不会把所有 skills 都塞进 default prompt。\n\n它使用 progressive disclosure。\n\n在 startup 或 capability refresh 时，Harness 扫描 skill folders：\n\n![](https://pbs.twimg.com/media/HKzsM9wXMAAb8YW.jpg)\n\nModel 可以看到这个 skill 存在。\n\n用户也可以通过 /skills 之类的 local command 看到它。\n\n完整 body 在 task 需要时才进入 context。\n\n## Where Skills.md Enters The Agent Turn \n\n![](https://pbs.twimg.com/media/HKzvMonXsAIKTBc.jpg)\n\nSKILL.md 先以 capability metadata 出现，task invoke 之后才加载 body。\n\n它进入 task procedure context：steps、tool expectations、checks、output shape。这个 context 只服务当前 workflow，不扩散成 always-on workspace policy。\n\n小小的 markdown，没有改变 model weights。\n\n却改变了该 task 里的 harness-managed context、tools 和 workflow。\n\n合适使用这些 markdown，是 coding agent 最关心的问题。\n\n而：\n\n> 在恰当的时机，把不同的 markdown 文件加载进context，就是 harness 应该做的事情。"}}