docs: add directory readmes and agent guides

2026-07-27 18:57:50 +00:00 · 2026-05-03 03:03:03 +08:00
parent ff7118ff01
commit a752c8172f
7 changed files with 217 additions and 1 deletions
@@ -9,6 +9,7 @@
 ```text
 docs/
 ├── README.md             # 知识库总索引
+├── AGENTS.md             # docs 总操作规则
 ├── getting-started/      # 从零开始、学习地图、环境与 AI CLI 配置
 ├── concepts/             # 核心概念、方法论与工程思想
 ├── philosophy/           # 哲学方法论、思维模型与底层认知模型
@@ -19,17 +20,25 @@ docs/
 ## 关键入口

 - `README.md`：知识库总索引。
+- `AGENTS.md`：`docs/` 总操作规则。
+- `concepts/README.md`：核心概念索引。
+- `concepts/AGENTS.md`：核心概念目录操作规则。
 - `getting-started/README.md`：从零开始完整入门，包含学习地图、Vibe Coding 经验、网络配置、CLI 配置与开发环境搭建。
+- `getting-started/AGENTS.md`：入门教程目录操作规则。
 - `concepts/拼好码.md`：复用优先、能力编排、边界治理与工程门禁。
 - `concepts/问题求解.md`：目标、现状、差距、标准与反馈迭代的底层能力。
 - `concepts/系统构建方法.md`：自顶向下、自底向上与分而治之的组合方法。
 - `concepts/开发范式演进.md`：软件工程组织方式的历史演进。
 - `concepts/递归自优化系统.md`：递归自优化生成系统的形式化模型。
 - `philosophy/README.md`：哲学方法论工具箱入口。
+- `philosophy/AGENTS.md`：哲学方法论目录操作规则。
 - `philosophy/思维模型.md`：可复用认知工具入口。
 - `philosophy/组合描述模型.md`：对象、状态、快照、序列、过程、变换、同一/差异与关系的组合描述模型。
 - `philosophy/编程之道.md`：编程哲学与工程判断入口。
+- `references/README.md`：参考资料索引。
+- `references/AGENTS.md`：参考资料目录操作规则。
 - `research/README.md`：新技术、技术栈、优秀 repo、工程范式和工具趋势研究入口。
+- `research/AGENTS.md`：研究笔记目录操作规则。
 - `research/Harness工程解析.md`：Harness Engineering 的工程控制、评估器与反馈闭环解析。
 - `references/工程实践.md`：项目架构、代码组织、开发经验、质量门禁与常见坑的统一入口。
 - `references/技术栈.md`：技术栈选型、组合案例与初学者学习路径。
@@ -40,12 +49,14 @@ docs/

 - 新增/修改文档内容。
 - 修复错误和过时信息。
- 为每个一级目录维护 `README.md` 作为索引入口（如存在）。
+- 为每个目录维护 `README.md` 作为索引入口。
+- 为每个目录维护 `AGENTS.md` 作为 Agent 操作规则。

 ### 禁止

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

 ## 命名规范

@@ -0,0 +1,39 @@
+# Concepts 目录 Agent 指南
+
+## 目录职责
+
+`docs/concepts/` 存放项目的核心概念与工程认知框架。
+
+这里的文档回答：
+
+- Vibe Coding 的基本概念是什么。
+- 新手如何定义问题、拆解问题和构建系统。
+- 工程方法如何从经验沉淀为可复用模型。
+
+## 文件地图
+
+```text
+concepts/
+├── README.md          # 核心概念索引
+├── AGENTS.md          # 本目录操作规则
+├── 拼好码.md          # 复用优先与胶水原则
+├── 问题求解.md        # 问题定义与求解框架
+├── 系统构建方法.md    # 自顶向下、自底向上、分而治之
+├── 开发范式演进.md    # 软件开发范式演进
+├── 语言层要素.md      # 代码理解所需语言层要素
+└── 递归自优化系统.md  # 递归自优化生成系统形式化
+```
+
+## 修改规则
+
+- 新增概念文档时，必须同步更新 `README.md`。
+- 重命名文件时，必须同步更新全仓链接和 `metadata/redirects.yml`。
+- 概念文档应优先使用稳定术语，避免同一概念多种叫法并存。
+- 不把一次性操作步骤放入本目录；操作型内容应放入 `docs/getting-started/`
+  或 `docs/references/`。
+
+## 质量要求
+
+- 每个概念先说明它解决的问题。
+- 尽量给出使用场景、判断标准和简单例子。
+- 不确定的外部事实必须标注 TODO 或迁移到 `docs/research/`。
@@ -0,0 +1,27 @@
+# 核心概念
+
+> `concepts/` 存放 Vibe Coding 的核心概念、问题求解框架、工程范式与系统构建方法。
+
+## 文档列表
+
+- [拼好码](拼好码.md) - 复用成熟能力，用胶水代码连接、编排、适配业务流程。
+- [问题求解](问题求解.md) - 用目标、现状、差距、标准、约束、对象和路径定义问题。
+- [系统构建方法](系统构建方法.md) - 自顶向下、自底向上与分而治之的组合使用。
+- [开发范式演进](开发范式演进.md) - 从面向过程到云原生的工程组织方式演进。
+- [语言层要素](语言层要素.md) - 看懂代码需要掌握的语言层要素。
+- [递归自优化系统](递归自优化系统.md) - 递归自优化生成系统的形式化模型。
+
+## 使用顺序
+
+建议先读：
+
+1. [问题求解](问题求解.md)
+2. [拼好码](拼好码.md)
+3. [系统构建方法](系统构建方法.md)
+4. [开发范式演进](开发范式演进.md)
+
+## 维护规则
+
+- 新增核心概念时，必须补充到本文档索引。
+- 文档命名应短、稳定、可引用。
+- 概念类文档优先解释“是什么、解决什么问题、如何使用”。
@@ -0,0 +1,34 @@
+# Getting Started 目录 Agent 指南
+
+## 目录职责
+
+`docs/getting-started/` 存放从零开始的线性入门教程。
+
+本目录面向：
+
+- 新电脑、新系统、零基础用户。
+- 第一次配置网络、Codex CLI、开发环境的人。
+- 想从想法走到可运行项目的学习者。
+
+## 文件地图
+
+```text
+getting-started/
+├── README.md   # 从零开始完整入门教程
+└── AGENTS.md   # 本目录操作规则
+```
+
+## 修改规则
+
+- 保持 `README.md` 作为单文件线性教程，避免重新拆散为多个碎片文档。
+- 新增步骤时，必须说明适用系统、前置条件、执行命令和成功判断。
+- 命令必须可复制执行；涉及平台差异时分别写明 Windows、WSL、Linux 或 macOS。
+- 默认路线优先是：网络环境和订阅准备 -> Codex CLI -> 让 Agent 配置后续环境。
+- 不把抽象方法论堆进本目录；方法论应链接到 `docs/concepts/` 或 `docs/references/`。
+
+## 质量要求
+
+- 假设读者没有前置依赖。
+- 每个关键步骤都要有失败时的处理方法。
+- 避免“自行安装”“配置一下”这类不可执行表述。
+- 修改后必须跑本地链接检查。
@@ -0,0 +1,35 @@
+# Philosophy 目录 Agent 指南
+
+## 目录职责
+
+`docs/philosophy/` 存放哲学方法论、思维模型、编程哲学与底层认知模型。
+
+这里的文档回答：
+
+- 如何建立可迁移的思维模型。
+- 如何从哲学和系统视角理解工程问题。
+- 如何用更底层的概念描述变化、关系和复杂度。
+
+## 文件地图
+
+```text
+philosophy/
+├── README.md        # 哲学方法论工具箱
+├── AGENTS.md        # 本目录操作规则
+├── 思维模型.md      # 可复用思维模型索引
+├── 组合描述模型.md  # 对象、状态、快照、序列、过程、变换、同一/差异与关系
+└── 编程之道.md      # 编程哲学与工程判断
+```
+
+## 修改规则
+
+- 新增模型时，优先补到 `思维模型.md`，再决定是否拆成独立文件。
+- 独立文件必须能被 `README.md` 或 `思维模型.md` 索引到。
+- 哲学内容必须落到工程判断或认知工具，不写成纯概念堆叠。
+- 重命名文件时，必须同步更新全仓链接和 `metadata/redirects.yml`。
+
+## 质量要求
+
+- 每个模型说明适用场景和使用方法。
+- 抽象概念应配工程例子或判断清单。
+- 保持术语稳定，避免同一模型出现多个标题口径。
@@ -0,0 +1,35 @@
+# References 目录 Agent 指南
+
+## 目录职责
+
+`docs/references/` 存放工程实践、技术栈、质量门禁、模板和检查清单。
+
+这里的文档回答：
+
+- 项目应该如何组织。
+- AI 编程应该如何设置硬门禁。
+- 常见技术栈如何选择和组合。
+- 工程经验如何变成可执行清单。
+
+## 文件地图
+
+```text
+references/
+├── README.md      # 参考资料索引
+├── AGENTS.md      # 本目录操作规则
+├── 工程实践.md    # 架构、代码组织、开发经验、质量门禁与常见坑
+└── 技术栈.md      # 技术栈选型、组合案例与学习路径
+```
+
+## 修改规则
+
+- 新增参考资料时，必须同步更新 `README.md`。
+- 检查清单、模板、质量门禁和经验类内容优先合并进 `工程实践.md`。
+- 技术选型、技术栈组合和学习路径优先合并进 `技术栈.md`。
+- 不在本目录写一次性研究笔记；新技术判断应先放入 `docs/research/`。
+
+## 质量要求
+
+- 参考文档必须可执行、可检查、可复用。
+- 门禁类内容尽量转成测试、CI、脚本、schema、类型或检查清单。
+- 不确定项必须标注 TODO，不能编造成熟结论。
@@ -0,0 +1,35 @@
+# Research 目录 Agent 指南
+
+## 目录职责
+
+`docs/research/` 存放新技术、新技术栈、优秀 repo、工程范式和工具趋势的短篇研究。
+
+这里的文档回答：
+
+- 它是什么。
+- 它解决什么问题。
+- 为什么值得关注。
+- 适合什么场景。
+- 有什么风险和替代方案。
+
+## 文件地图
+
+```text
+research/
+├── README.md             # 研究笔记索引
+├── AGENTS.md             # 本目录操作规则
+└── Harness工程解析.md    # Harness Engineering 技术解析
+```
+
+## 修改规则
+
+- 每篇研究笔记聚焦一个技术、repo、范式或工具。
+- 新增研究笔记时，必须同步更新 `README.md`。
+- 研究内容稳定后，可迁移到 `docs/concepts/`、`docs/references/` 或 `docs/philosophy/`。
+- 外部项目、模型、工具、版本和事实状态可能变化，涉及最新信息时必须核验来源。
+
+## 质量要求
+
+- 不写新闻转述，要给出判断、边界、采用建议和后续观察点。
+- 对不确定信息标注“待验证”或 TODO。
+- 引入外部事实时优先引用官方文档、原始仓库、论文或可信一手来源。