# Emerging Markdown Formats That Shape Coding Agent Behavior
**作者**: Bilgin Ibryam
**日期**: 2026-08-03T09:07:47.000Z
**来源**: [https://x.com/bibryam/status/2084204574559056207](https://x.com/bibryam/status/2084204574559056207)
---
Project knowledge is moving beside source code, where coding agents can discover it and turn intent into implementation.
For years, the knowledge required to change software lived across architecture documents, ADRs, security reviews, wikis, tickets, incident reports, and the heads of experienced developers.
The repository held the implementation. Developers gathered the surrounding context, applied judgment, and translated both into code.
That boundary is changing. An agent-ready repository increasingly carries not only source code, tests, configuration, and dependencies, but also the knowledge required to change them correctly.
A growing family of Markdown files captures that knowledge in forms coding agents can discover and use. Together, these files create a metacode layer: human intent and judgment made legible to the agent.
## 1. Onboarding and standing rules
A human joins a project once. A coding agent effectively onboards whenever it begins a task.
AGENTS.md is the closest thing to a neutral README for agents. It can describe repository structure, build and test commands, coding conventions, and pull request expectations. Nested files can add rules for a package or subsystem.
Vendor-native alternatives serve the same role: CLAUDE.md and .claude/rules/, GEMINI.md, GitHub Copilot instruction files, and .clinerules/.
These files answer: What should remain true across many tasks?
## 2. Skills package repeatable procedures
Standing rules are not the same as a procedure.
An agent skill describes how to perform a particular kind of work. A database migration skill might inspect the schema, create the migration, update generated types, run compatibility checks, verify rollback, and prepare the review summary.
The open Agent Skills specification packages this workflow in a required SKILL.md, with optional scripts, references, templates, and assets.
The boundary is useful:
- AGENTS.md carries standing context and constraints.
- SKILL.md carries a repeatable procedure invoked for a specific task.
## 3. Specs, plans, and tasks make change intent reviewable
Design and planning disappear when they exist only in chat. Versioned Markdown turns them into artifacts people can review before an agent implements them.
GitHub Spec Kit uses a clear chain:
1. spec.md records requirements and the desired outcome.
2. plan.md explains the technical design and implementation approach.
3. tasks.md breaks the plan into executable units.
4. The agent implements and validates the change.
OpenSpec, Kiro Specs, and project-specific PLANS.md files use different conventions, but they converge on the same separation: requirements, design, plan, tasks, implementation, and validation.
## 4. Domain files carry specialized context
Generic onboarding cannot fully describe every system.
ARCHITECTURE.md can capture system boundaries, dependencies, NFRs, and long-lived decisions. DESIGN.md can carry visual and design-system intent. AUTH.md can describe an authentication recipe. REVIEW.md can define code-review priorities and verification expectations.
Their maturity differs. ARCHITECTURE.md is an established documentation convention, while several domain-specific formats remain vendor-specific or experimental. The direction is nevertheless clear: specialized engineering knowledge is becoming directly legible to agents.
## 5. Memory makes learned context durable
Some knowledge is designed in advance. Other knowledge appears only while software is built and operated.
Agent memory preserves lessons such as an unexpected build prerequisite or a recurring debugging pattern across sessions. Claude Code makes an important distinction: humans write shared project guidance, while the agent writes auto memory into MEMORY.md and topic files stored outside the repository.
Machine-local memory should not silently become team truth. A practical promotion path is:
1. The agent records a tentative observation locally.
2. A human reviews it when it recurs or affects shared work.
3. Durable knowledge moves into a project rule, skill, ADR, or domain document.
Tentative knowledge stays local. Reviewed knowledge becomes shared.
## Put the metacode layer together
A project does not need every file. Use the smallest set agents can reliably discover. Keep reviewed knowledge beside the source code, and use vendor-specific files as thin compatibility bridges when another file is canonical.
The repository is becoming the meeting point between source code and metacode: requirements, NFRs, architecture, design, rules, procedures, plans, and durable learning.
When agents can read both, they act as intent compilers. Source code becomes the executable byproduct of human intent and judgment made legible to the agent.
The engineering task is to keep that metacode scoped, reviewed, and current. It does not replace testing or review. It gives the next code change a better source.
The full article includes the detailed format landscape, maturity notes, examples, and primary sources:
https://generativeprogrammer.com/p/emerging-markdown-formats-that-shape
## 相关链接
- [Bilgin Ibryam](https://x.com/bibryam)
- [@bibryam](https://x.com/bibryam)
- [6.5K](https://x.com/bibryam/status/2084204574559056207/analytics)
- [AGENTS.md](https://agents.md/)
- [Agent Skills specification](https://agentskills.io/specification)
- [GitHub Spec Kit](https://github.github.com/spec-kit/index.html)
- [https://generativeprogrammer.com/p/emerging-markdown-formats-that-shape](https://generativeprogrammer.com/p/emerging-markdown-formats-that-shape)
- [Upgrade to Premium](https://x.com/i/premium_sign_up)
- [5:07 PM · Aug 3, 2026](https://x.com/bibryam/status/2084204574559056207)
- [6,543 Views](https://x.com/bibryam/status/2084204574559056207/analytics)
---
*导出时间: 2026/8/4 09:28:22*
---
## 中文翻译
# 塑造编码代理行为的兴起中的 Markdown 格式
**作者**: Bilgin Ibryam
**日期**: 2026-08-03T09:07:47.000Z
**来源**: [https://x.com/bibryam/status/2084204574559056207](https://x.com/bibryam/status/2084204574559056207)
---
项目知识正在向源代码靠拢，以便编码代理能够发现这些知识，并将意图转化为实现。
多年来，更改软件所需的知识分散存在于架构文档、ADR（架构决策记录）、安全审查、Wiki、工单、事故报告以及经验丰富的开发人员的脑海中。
代码库托管着实现。开发人员收集周围的上下文，运用判断力，并将二者转化为代码。
这一界限正在发生变化。一个代理就绪（agent-ready）的代码库越来越多地不仅包含源代码、测试、配置和依赖项，还包含正确更改它们所需的知识。
一个日益庞大的 Markdown 文件家族以编码代理可以发现并使用的形式捕获了这些知识。这些文件共同创建了一个元代码层：使人类意图和判断对代理可见。
## 1. 入门与常驻规则
人类加入一个项目只有一次。而编码代理实际上每次开始任务时都需要进行入门。
AGENTS.md 是最接近于面向代理的中立性 README 的文件。它可以描述代码库结构、构建和测试命令、编码约定以及拉取请求的预期。嵌套文件可以添加针对特定包或子系统的规则。
供应商原生的替代方案发挥着相同的作用：CLAUDE.md 和 .claude/rules/、GEMINI.md、GitHub Copilot 指令文件以及 .clinerules/。
这些文件回答了这样一个问题：在许多任务中，哪些东西应始终保持不变？
## 2. 技能封装可重复的过程
常驻规则不等同于过程。
代理技能描述了如何执行特定类型的工作。数据库迁移技能可能会检查架构、创建迁移、更新生成的类型、运行兼容性检查、验证回滚并准备审查摘要。
开放的 Agent Skills 规范将此工作流封装在必需的 SKILL.md 中，并辅以可选的脚本、引用、模板和资源。
这种区分很有用：
- AGENTS.md 承载常驻上下文和约束。
- SKILL.md 承载针对特定任务调用的可重复过程。
## 3. 规范、计划和任务使变更意图可审查
设计和规划如果仅存在于聊天中，就会消失。版本化的 Markdown 将它们转化为人工制品，人们可以在代理实施之前对其进行审查。
GitHub Spec Kit 使用了一条清晰的链：
1. spec.md 记录需求和期望的结果。
2. plan.md 解释技术设计和实施方法。
3. tasks.md 将计划分解为可执行的单元。
4. 代理实施并验证变更。
OpenSpec、Kiro Specs 和项目特定的 PLANS.md 文件使用不同的约定，但它们在同一个分离点上趋于一致：需求、设计、计划、任务、实施和验证。
## 4. 领域文件承载特定的上下文
通用的入门无法完全描述每一个系统。
ARCHITECTURE.md 可以捕获系统边界、依赖项、非功能性需求（NFR）和长期决策。DESIGN.md 可以承载视觉和设计系统的意图。AUTH.md 可以描述身份验证方案。REVIEW.md 可以定义代码审查的优先级和验证预期。
它们的成熟度各不相同。ARCHITECTURE.md 是一种既定的文档约定，而几种特定领域的格式仍然特定于供应商或处于实验阶段。但方向是明确的：专业的工程知识正变得对代理直接可见。
## 5. 记忆使学习到的上下文持久化
有些知识是预先设计的。而其他知识只有在软件构建和运行过程中才会出现。
代理记忆保存诸如意外的构建先决条件或重复出现的调试模式等经验教训。Claude Code 做出了一个重要的区分：人类编写共享的项目指导，而代理将自动记忆写入 MEMORY.md 和存储在代码库之外的主题文件中。
机器本地的记忆不应悄无声息地成为团队的事实。一个切实可行的晋升路径是：
1. 代理在本地记录临时性的观察。
2. 当观察结果重复出现或影响共享工作时，人类对其进行审查。
3. 持久化的知识转移到项目规则、技能、ADR 或领域文档中。
暂定性的知识保留在本地。经过审查的知识变为共享知识。
## 组合元代码层
一个项目并不需要每个文件。使用代理可以可靠发现的最小集合。将经过审查的知识与源代码放在一起，并在另一个文件作为标准来源时，将供应商特定的文件用作精简的兼容性桥梁。
代码库正成为源代码和元代码之间的交汇点：需求、非功能性需求（NFR）、架构、设计、规则、过程、计划和持久的学习。
当代理能够读取这两者时，它们就充当了意图编译器。源代码成为了人类意图和判断对代理可见后的可执行副产品。
工程任务是保持该元代码的范围适度、经过审查且为最新状态。它并不取代测试或审查。它为下一次代码变更提供了更好的来源。
完整的文章包括详细的格式格局、成熟度说明、示例和主要来源：
https://generativeprogrammer.com/p/emerging-markdown-formats-that-shape
## 相关链接
- [Bilgin Ibryam](https://x.com/bibryam)
- [@bibryam](https://x.com/bibryam)
- [6.5K](https://x.com/bibryam/status/2084204574559056207/analytics)
- [AGENTS.md](https://agents.md/)
- [Agent Skills specification](https://agentskills.io/specification)
- [GitHub Spec Kit](https://github.github.com/spec-kit/index.html)
- [https://generativeprogrammer.com/p/emerging-markdown-formats-that-shape](https://generativeprogrammer.com/p/emerging-markdown-formats-that-shape)
- [Upgrade to Premium](https://x.com/i/premium_sign_up)
- [5:07 PM · Aug 3, 2026](https://x.com/bibryam/status/2084204574559056207)
- [6,543 Views](https://x.com/bibryam/status/2084204574559056207/analytics)
---
*导出时间: 2026/8/4 09:28:22* 
