---
title: "AGENTS.md 只当目录，细节放 docs/index.md"
summary: "主文件只教怎么找上下文。架构、领域和跨目录概念放到带 index.md 和 @tag 的文档树。"
category: agents-md
level: intermediate
surfaces: [cli, app, ide]
tags: ["AGENTS.md", "文档", "检索"]
canonical: /tips/agents-md-as-index/
---

# AGENTS.md 只当目录，细节放 docs/index.md

主文件只教怎么找上下文。架构、领域和跨目录概念放到带 index.md 和 @tag 的文档树。

`AGENTS.md` 适合当入口，不适合当百科。社区里一套可执行的拆法：

1. `AGENTS.md` 只写导航：先搜哪、必读哪份、完成后要不要回写文档
2. 结构化说明进 `docs/`，每个有意义的目录放 `index.md`，用一两句话指向子页
3. 跨目录概念用 `@tag:auth-bootstrap` 这类记号同时标在文档和代码注释里
4. 用一份短的 `docs/tags.md` 给每个 tag 一个含义，避免同名乱飘

这仍然是 Markdown + 文本搜索，不依赖某家 IDE 的向量索引。Codex、人类和 `rg` 走同一层。

不要把临时环境状态写进这棵树。瞬时事实让它开工时自己探测。

## 来源

- [OpenAI Community · repo-native context pattern](https://community.openai.com/t/a-repo-native-context-pattern-for-codex-agents-md-index-md-searchable-tags/1386068)
- [mpashka/llm-wiki-tags](https://github.com/mpashka/llm-wiki-tags)