mirror of https://github.com/tradecatlabs/vibe-coding-cn.git synced 2026-07-27 18:57:50 +00:00

Files

T

tradecatlabs f1f0b9fe75 refactor: move research domain to repository root (#58 )

Move the complete research domain from docs/research to root-level research, update indexes and path-aware tooling, and align raw snapshot governance and CODEOWNERS.\n\nVerified with make test and GitHub CI.

2026-07-11 22:18:37 +08:00

4.4 KiB

Raw Permalink Blame History

Documents 目录 Agent 指南

目录用途

docs/ 存放项目核心知识库文档，包含入门路径、核心概念、哲学方法论、参考清单和工作流。根级 research/ 承载新技术、优秀 repo 和工程范式研究；docs/ 只保留到研究域的导航链接。

目录结构

docs/
├── README.md             # 知识库总索引
├── AGENTS.md             # docs 总操作规则
├── getting-started/      # 从零开始、学习地图、环境与 AI CLI 配置
├── concepts/             # 索引 + 独立正文文档：核心概念、问题求解与工程思想
├── philosophy/           # 索引 + 独立正文文档：哲学方法论、思维模型与底层认知模型
├── references/           # 索引 + 独立正文文档：工程实践、技术栈、清单与质量门禁
└── workflow/             # 索引 + 独立正文文档：开发流程、质量门禁、版本控制和文档同步

关键入口

README.md：知识库总索引。
AGENTS.md：docs/ 总操作规则。
getting-started/README.md：从零开始索引，正文拆分为学习地图、Vibe Coding 经验、网络配置、CLI 配置与开发环境搭建。
getting-started/AGENTS.md：入门教程目录操作规则。
concepts/README.md：核心概念索引，正文拆分到同目录主题文档。
concepts/AGENTS.md：核心概念目录操作规则。
philosophy/README.md：哲学方法论索引，正文拆分到同目录主题文档。
philosophy/AGENTS.md：哲学方法论目录操作规则。
references/README.md：参考资料索引，正文拆分到同目录模板、清单和技术栈文档。
references/AGENTS.md：参考资料目录操作规则。
../research/README.md：根级研究索引，正文拆分到研究对象目录或短篇研究笔记。
../research/AGENTS.md：根级研究域操作规则。
workflow/README.md：流程索引，正文拆分到同目录流程文档。
workflow/AGENTS.md：开发流程目录操作规则。

操作规范

允许

新增/修改文档内容。
修复错误和过时信息。
为每个目录维护 README.md 作为索引入口。
为每个目录维护 AGENTS.md 作为 Agent 操作规则。

禁止

删除现有文档（除非明确要求）。
大规模重命名/移动文件导致链接失效（如必须调整，需同步更新引用）。
新增目录但不补 README.md 和 AGENTS.md。

README 结构契约

所有 docs/**/README.md 必须面向人类阅读，按以下标准块顺序组织：

顶部标题块：只允许一个 H1，且 H1 后必须直接进入 ## 字多不看。
## 字多不看：用 3-7 条说明最短判断和阅读入口。
## 快速导航：列出主要章节、路线或常用入口。
完整细粒度目录（点击展开/收起）：使用标准 <details>/<summary> 折叠块。
## 使用方式：说明人类读者如何使用本文档。
## 正文：只说明正文已拆分到独立文档；README 不再承载长正文。

禁止在 README 中出现以下结构：

H1 和 ## 字多不看 之间的引用块、说明段或任何夹层内容。
### 和其他目录的边界。
### 维护规则。
“本目录只保留”“不再新增”“同步 metadata”“同步 AI 引用”等维护者口径。

这些维护规则必须写入对应 AGENTS.md，不写入面向人类的 README。

维护规则

每个目录必须同时维护 README.md 和 AGENTS.md。
新增、删除、移动、重命名 docs 文档时，必须同步更新 docs/README.md、所在目录 README 索引和 metadata/taxonomy.yml。
新增、删除、移动、重命名 research 文档时，必须同步更新根级 research/README.md、必要的 docs/README.md 跨入口、根 README.md、metadata/taxonomy.yml 和必要的 metadata/redirects.yml。
面向 AI 引用的重要入口变化，必须同步更新 assets/ai-citation/llms-full.txt 和相关摘要文件。
不确定信息标注 TODO，不用猜测补齐。
修改任意 docs README 后，运行 make sync-doc-toc 和 make test。
make check-doc-structure 是 README 结构契约硬门禁；失败时必须先修结构，再继续提交。

命名规范

文件名使用中文或清晰英文。
使用 Markdown 格式。
目录名使用简短英文，保证跨平台与链接稳定。

4.4 KiB Raw Permalink Blame History Unescape Escape