Markdown is a lightweight markup language for formatting plain-text documents. In agent workflows, it carries externalized state such as specifications, plans, conventions, and project knowledge across context windows. section 3.5.3
Markdown also creates an integration boundary: generated content may be readable to people but unusable to software until its formatting is removed. SQL generation, for example, requires stripping fenced Markdown before execution. section 6.2
Use Markdown deliberately rather than treating it as accumulated project memory:
- Externalize architecture, schemas, conventions, organizational policies, historical decisions, and operational knowledge in structured files. section 3.5.3
- Expect orchestration overhead and additional failure modes when Markdown files become part of multi-agent workflows. section 3.5.3
- Clean generated Markdown fences when downstream systems require executable SQL rather than formatted prose. section 6.2
Externalized project state
A project can preserve accumulated intelligence in a .planning/ directory, skill files, CLAUDE.md, and AGENTS.md, giving fresh agent sessions immediate access to shared context. section 3.5.3
Figure 3.11 The context pyramid: five interdependent layers of the Context Fabric. Each layer rests on the ones below it - a gap low in the pyramid undermines everything above, no matter how complete the upper layers are.

The context pyramid shows how Markdown-held knowledge can span system, code, organizational, historical, and operational context, with gaps in lower layers weakening higher layers. section 3.5.3

