Markdown Is A Context Interface

Harness 系列文章之 5，小小的 markdown 文件，却可以改变 Coding Agent 的世界状态。

.md file works when the harness knows what kind of context it is.

现代 coding agent 里，一个很有意思的现象是：普通 markdown 文件可以改变 agent behavior。

加一个 AGENTS.md，Agent 开始遵守 repo-specific rules。

加一个 SKILL.md，Agent 在某类 task 上突然更稳定。

Markdown file 只是可见部分。

真正有趣的是 Harness 对这种机制的设计：

The Naive Markdown Dump

按照习惯，如果我们从一个从 tiny agent 看 markdown：

这看起来合理，因为 rules，docs，plans，procedures 都经常写在 markdown 里。

但 raw markdown dumping 有代价：

• 旧 notes 会和当前 instructions 竞争

• 长 docs 会挤掉最近的 tool result

• drafts 可能被误当成 rules

• general project guidance 可能盖过 narrow task procedure

Model 得到了更多 text，但 task 得到的有用的 instruction 更少。

所以，

.md 应该通过 Harness route 进入 context，不能直接倒进 prompt。

Two Files, Two Jobs

这里，我们可以一起看两个常用 markdown files，AGENTS.md 以及 SKILLS.md

它们都是 markdown, 但进入 prompt 的方式不一样。

AGENTS.md ：In this workspace, behave like this.

SKILL.md ：For this kind of task, use this procedure.

Why AGENTS.md Works

AGENTS.md 有效，是因为 Harness 把它当成 workspace instruction context。

它是 project guidance，应该在 model 开始操作 repo 前可见。

例如我自己的 Dongxi Agent 主要任务是要根据每天与 coding agent的交互中，总结学习经验。

那么，在 DongXi 这个 workspace 里，AGENTS.md 要求：做 DongXi Agent 或 coding-agent harness learning 时，要保持 learning artifact current。

这一个文件会改变整个 session 的行为：

Model 仍然负责 writing 和 reasoning。

但 Harness 在 turn 开始前插入了稳定的 project rule。

这就是 AGENTS.md 强的地方：

• 它从 workspace 被发现

• 它被 project 或 directory scope 限定

• 它进入 stable instruction layer

• 它跨多个 tasks 持续生效

• 它让用户不必在每个 prompt 里重复 local conventions

How AGENTS.md Works

• Harness 应该知道每条 rule 适用于哪个 directory。

• nested workspace 可能有更窄的 rules。

• 这些 rules 应该被当成 instruction context，同时仍然低于 system 和 developer policy。

• 文件内容不应该被盲目复制进每条 visible transcript message。

• 它属于 stable context layer。

这样 prompt 可以保持一致，又不会把 project rules 变成 noisy chat history。

Where Agents.md Enters The Agent Turn

AGENTS.md 在 model turn 组装前加载。

它进入 stable workspace instruction context，和 project rules、local operating constraints 放在一起。transcript 记录发生了什么；AGENTS.md 约束接下来该怎么做。

Why SKILL.md Works

SKILL.md 有效，原因不同。

它能提升某类 task 的表现，是因为它在正确时机给 model 一个聚焦的 procedure。

没有 skill 时，model 可能懂一般领域，但会漏掉 local workflow。

有 skill 时，Harness 可以提供：

• 什么时候使用这个 workflow

• 哪些 files 或 artifacts 重要

• 哪些 tools 被允许或期待使用

• 应该按什么步骤做

• 什么 checks 证明工作完成

• 用户期待什么 output format

这比一句 vague prompt 强得多：

这个文件会提升 performance，因为它把 fuzzy ability 变成 repeatable procedure。

How SKILL.md Works

好的 Harness 不会把所有 skills 都塞进 default prompt。

它使用 progressive disclosure。

在 startup 或 capability refresh 时，Harness 扫描 skill folders：

Model 可以看到这个 skill 存在。

用户也可以通过 /skills 之类的 local command 看到它。

完整 body 在 task 需要时才进入 context。

Where Skills.md Enters The Agent Turn

SKILL.md 先以 capability metadata 出现，task invoke 之后才加载 body。

它进入 task procedure context：steps、tool expectations、checks、output shape。这个 context 只服务当前 workflow，不扩散成 always-on workspace policy。

小小的 markdown，没有改变 model weights。

却改变了该 task 里的 harness-managed context、tools 和 workflow。

合适使用这些 markdown，是 coding agent 最关心的问题。

而：

在恰当的时机，把不同的 markdown 文件加载进context，就是 harness 应该做的事情。