From a752c8172f5c416c64fdf5a8c8d873371e2cb6d7 Mon Sep 17 00:00:00 2001 From: tukuaiai Date: Sun, 3 May 2026 03:03:03 +0800 Subject: [PATCH] docs: add directory readmes and agent guides --- docs/AGENTS.md | 13 +++++++++++- docs/concepts/AGENTS.md | 39 ++++++++++++++++++++++++++++++++++ docs/concepts/README.md | 27 +++++++++++++++++++++++ docs/getting-started/AGENTS.md | 34 +++++++++++++++++++++++++++++ docs/philosophy/AGENTS.md | 35 ++++++++++++++++++++++++++++++ docs/references/AGENTS.md | 35 ++++++++++++++++++++++++++++++ docs/research/AGENTS.md | 35 ++++++++++++++++++++++++++++++ 7 files changed, 217 insertions(+), 1 deletion(-) create mode 100644 docs/concepts/AGENTS.md create mode 100644 docs/concepts/README.md create mode 100644 docs/getting-started/AGENTS.md create mode 100644 docs/philosophy/AGENTS.md create mode 100644 docs/references/AGENTS.md create mode 100644 docs/research/AGENTS.md diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 30302b2..f92938f 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -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`。 ## 命名规范 diff --git a/docs/concepts/AGENTS.md b/docs/concepts/AGENTS.md new file mode 100644 index 0000000..13de938 --- /dev/null +++ b/docs/concepts/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/`。 diff --git a/docs/concepts/README.md b/docs/concepts/README.md new file mode 100644 index 0000000..a3d8259 --- /dev/null +++ b/docs/concepts/README.md @@ -0,0 +1,27 @@ +# 核心概念 + +> `concepts/` 存放 Vibe Coding 的核心概念、问题求解框架、工程范式与系统构建方法。 + +## 文档列表 + +- [拼好码](拼好码.md) - 复用成熟能力，用胶水代码连接、编排、适配业务流程。 +- [问题求解](问题求解.md) - 用目标、现状、差距、标准、约束、对象和路径定义问题。 +- [系统构建方法](系统构建方法.md) - 自顶向下、自底向上与分而治之的组合使用。 +- [开发范式演进](开发范式演进.md) - 从面向过程到云原生的工程组织方式演进。 +- [语言层要素](语言层要素.md) - 看懂代码需要掌握的语言层要素。 +- [递归自优化系统](递归自优化系统.md) - 递归自优化生成系统的形式化模型。 + +## 使用顺序 + +建议先读： + +1. [问题求解](问题求解.md) +2. [拼好码](拼好码.md) +3. [系统构建方法](系统构建方法.md) +4. [开发范式演进](开发范式演进.md) + +## 维护规则 + +- 新增核心概念时，必须补充到本文档索引。 +- 文档命名应短、稳定、可引用。 +- 概念类文档优先解释“是什么、解决什么问题、如何使用”。 diff --git a/docs/getting-started/AGENTS.md b/docs/getting-started/AGENTS.md new file mode 100644 index 0000000..cbcc331 --- /dev/null +++ b/docs/getting-started/AGENTS.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/`。 + +## 质量要求 + +- 假设读者没有前置依赖。 +- 每个关键步骤都要有失败时的处理方法。 +- 避免“自行安装”“配置一下”这类不可执行表述。 +- 修改后必须跑本地链接检查。 diff --git a/docs/philosophy/AGENTS.md b/docs/philosophy/AGENTS.md new file mode 100644 index 0000000..fd58e88 --- /dev/null +++ b/docs/philosophy/AGENTS.md @@ -0,0 +1,35 @@ +# Philosophy 目录 Agent 指南 + +## 目录职责 + +`docs/philosophy/` 存放哲学方法论、思维模型、编程哲学与底层认知模型。 + +这里的文档回答： + +- 如何建立可迁移的思维模型。 +- 如何从哲学和系统视角理解工程问题。 +- 如何用更底层的概念描述变化、关系和复杂度。 + +## 文件地图 + +```text +philosophy/ +├── README.md # 哲学方法论工具箱 +├── AGENTS.md # 本目录操作规则 +├── 思维模型.md # 可复用思维模型索引 +├── 组合描述模型.md # 对象、状态、快照、序列、过程、变换、同一/差异与关系 +└── 编程之道.md # 编程哲学与工程判断 +``` + +## 修改规则 + +- 新增模型时，优先补到 `思维模型.md`，再决定是否拆成独立文件。 +- 独立文件必须能被 `README.md` 或 `思维模型.md` 索引到。 +- 哲学内容必须落到工程判断或认知工具，不写成纯概念堆叠。 +- 重命名文件时，必须同步更新全仓链接和 `metadata/redirects.yml`。 + +## 质量要求 + +- 每个模型说明适用场景和使用方法。 +- 抽象概念应配工程例子或判断清单。 +- 保持术语稳定，避免同一模型出现多个标题口径。 diff --git a/docs/references/AGENTS.md b/docs/references/AGENTS.md new file mode 100644 index 0000000..1616874 --- /dev/null +++ b/docs/references/AGENTS.md @@ -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，不能编造成熟结论。 diff --git a/docs/research/AGENTS.md b/docs/research/AGENTS.md new file mode 100644 index 0000000..48353f3 --- /dev/null +++ b/docs/research/AGENTS.md @@ -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。 +- 引入外部事实时优先引用官方文档、原始仓库、论文或可信一手来源。