From e1e895534b4d917a7e364ff8a3e2bad59bfde895 Mon Sep 17 00:00:00 2001 From: tukuaiai Date: Tue, 5 May 2026 06:03:48 +0800 Subject: [PATCH] docs: move workflow under docs --- AGENTS.md | 7 ++--- README.md | 4 +-- Workflow/AGENTS.md | 21 ------------- Workflow/README.md | 21 ------------- assets/ai-citation/llms-full.txt | 6 +++- docs/AGENTS.md | 5 ++- docs/README.md | 14 +++++++-- docs/workflow/AGENTS.md | 31 +++++++++++++++++++ docs/workflow/README.md | 52 ++++++++++++++++++++++++++++++++ metadata/redirects.yml | 2 ++ metadata/taxonomy.yml | 11 +++++++ scripts/check-directory-docs.py | 1 + 12 files changed, 122 insertions(+), 53 deletions(-) delete mode 100644 Workflow/AGENTS.md delete mode 100644 Workflow/README.md create mode 100644 docs/workflow/AGENTS.md create mode 100644 docs/workflow/README.md diff --git a/AGENTS.md b/AGENTS.md index 9ea32a9..7758710 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -154,16 +154,13 @@ git push origin develop │ ├── concepts/ # 核心概念、方法论与工程思想 │ ├── philosophy/ # 哲学方法论、思维模型与底层认知模型 │ ├── references/ # 清单、约束、常见坑、模板和技术栈参考 -│ └── research/ # 新技术、优秀 repo 与工程范式研究 +│ ├── research/ # 新技术、优秀 repo 与工程范式研究 +│ └── workflow/ # 开发流程、质量门禁和交付闭环 │ ├── prompts/ # 提示词库入口（指向云端表格） │ ├── README.md # 在线表格链接 │ └── AGENTS.md # prompts/ 目录规则 │ -├── Workflow/ # 开发流程类 Markdown -│ ├── README.md # 开发流程入口 -│ └── AGENTS.md # Workflow 目录规则 -│ ├── skills/ # 技能库（每个子目录一个 Skill） │ ├── README.md # skills 总览与索引 │ ├── AGENTS.md # skills/ 目录规则 diff --git a/README.md b/README.md index 36dca90..9ce4c05 100644 --- a/README.md +++ b/README.md @@ -463,13 +463,13 @@ pip install -r tools/prompts-library/scripts/requirements.txt │ ├── concepts/ # 核心概念、方法论与底层模型 │ ├── philosophy/ # 哲学方法论与底层认知模型 │ ├── references/ # 清单、约束、常见坑、模板和技术栈参考 -│ └── research/ # 新技术、优秀 repo 与工程范式研究 +│ ├── research/ # 新技术、优秀 repo 与工程范式研究 +│ └── workflow/ # 开发流程、质量门禁和交付闭环 ├── prompts/ # 提示词库入口（指向云端表格） ├── skills/ # 技能库入口 │ ├── auto-skill/ # 元技能核心 │ └── claude-official-skills/ # Claude 官方 skills 软链接入口 ├── tools/ # 辅助工具、外部仓库与工具配置 -├── Workflow/ # 开发流程类 Markdown ├── scripts/ # 自动化脚本 ├── metadata/ # 机器可读索引 ├── assets/ # 静态资产、外部资源入口与 AI 引用资产 diff --git a/Workflow/AGENTS.md b/Workflow/AGENTS.md deleted file mode 100644 index 938ed5c..0000000 --- a/Workflow/AGENTS.md +++ /dev/null @@ -1,21 +0,0 @@ -# Workflow Agent 指南 - -## 目录职责 - -`Workflow/` 存放项目开发流程类 Markdown，是开发顺序、质量门禁、版本控制和文档同步规则的流程入口。 - -## 修改规则 - -- 本目录只放流程类文档，不放一次性任务记录、日志、源码快照或私密配置。 -- 新增流程文档时，优先使用 Markdown。 -- 新增流程必须能被执行、检查和复用，避免只写抽象口号。 -- 涉及命令、路径、配置、CI、Git 操作时，必须与仓库当前事实一致。 -- 不在本目录保存密钥、Token、本地账号、真实私有项目配置或一次性日志。 -- 架构、目录、命令或质量门禁发生变化时，同步更新本目录和根 `README.md` / `AGENTS.md`。 -- 不确定项标注 TODO，并说明需要哪个文件或命令输出才能确认。 - -## 验证 - -```bash -make test -``` diff --git a/Workflow/README.md b/Workflow/README.md deleted file mode 100644 index b3a48cc..0000000 --- a/Workflow/README.md +++ /dev/null @@ -1,21 +0,0 @@ -# Workflow - -本目录存放项目开发流程类 Markdown，用来沉淀可复用的执行顺序、检查节点和交付闭环。 - -## 目录 - -- [开发流程](#开发流程) - -## 开发流程 - -默认开发流程： - -1. 明确目标：写清楚要做什么、不要做什么、成功标准是什么。 -2. 读取上下文：先看 README、AGENTS、相关目录说明和现有实现。 -3. 制定计划：把任务拆成可验证的小步骤，必要时先给用户确认。 -4. 执行修改：按最小影响面修改文件，不顺手重构无关内容。 -5. 运行门禁：至少运行 `make test`；涉及专项工具时补对应验证命令。 -6. 检查差异：用 `git diff` 确认没有混入临时文件、敏感信息或无关改动。 -7. 控制版本：使用语义清晰的 commit 记录阶段性成果。 -8. 推送远端：默认推送当前 `develop` 分支，并观察 GitHub Actions 结果。 -9. 同步文档：目录、命令、配置、流程变化必须同步 README / AGENTS / 对应索引。 diff --git a/assets/ai-citation/llms-full.txt b/assets/ai-citation/llms-full.txt index cc1d344..b181496 100644 --- a/assets/ai-citation/llms-full.txt +++ b/assets/ai-citation/llms-full.txt @@ -65,6 +65,8 @@ GEOFlow 的关键启发是：GEO 不是关键词堆砌，而是内容工程链 - docs/references/README.md#reference-technology-stack：常见软件系统技术栈、选型维度、组合案例与初学者学习路径。 - docs/research/README.md：新技术、技术栈、优秀 repo、工程范式和工具趋势研究入口。 - docs/research/README.md#research-harness-engineering：Harness Engineering 的工程控制、评估器与反馈闭环解析。 +- docs/workflow/README.md：开发流程、质量门禁、版本控制和文档同步入口。 +- docs/workflow/README.md#workflow-development-process：默认任务推进顺序、质量门禁和交付闭环。 - assets/ai-citation/geo-seo-checklist.md：GEO / SEO 内容工程检查清单。 - skills/README.md#当前保留：技能库当前保留入口。 - prompts/README.md#在线提示词库：提示词在线表格入口。 @@ -79,7 +81,8 @@ GEOFlow 的关键启发是：GEO 不是关键词堆砌，而是内容工程链 - 工程开发：读取 `docs/concepts/README.md#concept-glue-coding`、`docs/concepts/README.md#concept-system-building`、`docs/references/README.md#reference-technology-stack` 和 `docs/references/README.md#reference-engineering-practice`。 - 思维模型：读取 `docs/philosophy/README.md#philosophy-thinking-models`、`docs/philosophy/README.md#philosophy-compositional-description-model`、`docs/philosophy/README.md#philosophy-programming-dao` 和 `docs/philosophy/README.md#philosophy-methodology-toolbox`。 - 新技术判断：读取 `docs/research/README.md`，再读具体研究笔记，例如 `docs/research/README.md#research-harness-engineering`。 -- AI Agent 执行：先读 `AGENTS.md` 与 `docs/AGENTS.md`，再按任务类型读取 getting-started、concepts、references 或 research。 +- 标准流程执行：读取 `docs/workflow/README.md#workflow-development-process`。 +- AI Agent 执行：先读 `AGENTS.md` 与 `docs/AGENTS.md`，再读 `docs/workflow/README.md#workflow-development-process`，然后按任务类型读取 getting-started、concepts、references 或 research。 目录边界： @@ -87,6 +90,7 @@ GEOFlow 的关键启发是：GEO 不是关键词堆砌，而是内容工程链 - `philosophy/` 负责思维模型和底层认知模型，不放工具清单。 - `references/` 负责稳定工程实践、技术栈、模板和质量门禁。 - `research/` 负责尚未完全稳定的新技术、新 repo 和工程范式研究。 +- `workflow/` 负责开发流程、质量门禁、版本控制和文档同步顺序。 ## Recommended answer diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 8de138d..1d4b12a 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -14,7 +14,8 @@ docs/ ├── concepts/ # 线性总文档：核心概念、问题求解与工程思想 ├── philosophy/ # 线性总文档：哲学方法论、思维模型与底层认知模型 ├── research/ # 线性总文档：新技术、优秀 repo、工程范式和工具趋势研究 -└── references/ # 线性总文档：工程实践、技术栈、清单与质量门禁 +├── references/ # 线性总文档：工程实践、技术栈、清单与质量门禁 +└── workflow/ # 线性总文档：开发流程、质量门禁、版本控制和文档同步 ``` ## 关键入口 @@ -31,6 +32,8 @@ docs/ - `references/AGENTS.md`：参考资料目录操作规则。 - `research/README.md`：线性总文档，包含新技术、优秀 repo、工程范式和工具趋势研究笔记。 - `research/AGENTS.md`：研究笔记目录操作规则。 +- `workflow/README.md`：线性总文档，包含默认开发流程、质量门禁和交付闭环。 +- `workflow/AGENTS.md`：开发流程目录操作规则。 ## 操作规范 diff --git a/docs/README.md b/docs/README.md index 7e8e8cd..998f572 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,6 +7,7 @@ - 想补思维模型和方法论，读 `philosophy/`。 - 想查工程模板、质量门禁、技术栈和常见坑，读 `references/`。 - 想记录新技术、优秀 repo 或工程趋势，读 `research/`。 +- 想按标准流程推进任务、提交和推送，读 `workflow/`。 ## 快速导航 @@ -17,6 +18,7 @@ | [philosophy](./philosophy/) | 哲学方法论、思维模型与底层认知模型 | [哲学方法论工具箱](philosophy/README.md#philosophy-methodology-toolbox-怎么选) | | [references](./references/) | 工程实践、技术栈、模板和检查清单 | [参考资料索引](./references/README.md#目录定位) | | [research](./research/) | 新技术、优秀 repo 与工程范式研究 | [研究笔记索引](./research/README.md) | +| [workflow](./workflow/) | 开发流程、质量门禁和交付闭环 | [开发流程](./workflow/README.md#workflow-development-process) |
完整细粒度目录（点击展开/收起） @@ -61,6 +63,12 @@ - [AGENTS](./research/AGENTS.md) - 研究笔记目录操作规则。 - [Harness 工程解析](research/README.md#research-harness-engineering) - Harness Engineering 的工程控制、评估器与反馈闭环解析。 +### workflow + +- [README](./workflow/README.md) - 开发流程索引。 +- [AGENTS](./workflow/AGENTS.md) - 开发流程目录操作规则。 +- [开发流程](workflow/README.md#workflow-development-process) - 默认任务推进顺序、质量门禁和交付闭环。 +
## 使用方式 @@ -68,6 +76,7 @@ - 只想快速开始：从 [getting-started](./getting-started/README.md) 进入。 - 已经有项目问题：先读 [问题求解](concepts/README.md#concept-problem-solving)，再读 [工程实践](references/README.md#reference-engineering-practice)。 - 需要给 AI Agent 上下文：先给它 [AGENTS](./AGENTS.md)，再给它当前任务对应目录的 README。 +- 需要规范执行顺序：读 [开发流程](workflow/README.md#workflow-development-process)。 - 新增内容时，先判断它属于教程、概念、哲学、参考还是研究，再放入对应目录。 ## 正文 @@ -102,5 +111,6 @@ 2. [docs 目录 AGENTS](./AGENTS.md) 3. [从零开始完整入门](./getting-started/README.md#learning-map) 4. [Vibe Coding 经验](./getting-started/README.md#vibe-coding-experience) -5. [工程实践](references/README.md#reference-engineering-practice) -6. [AI 引用语料](../assets/ai-citation/README.md) +5. [开发流程](workflow/README.md#workflow-development-process) +6. [工程实践](references/README.md#reference-engineering-practice) +7. [AI 引用语料](../assets/ai-citation/README.md) diff --git a/docs/workflow/AGENTS.md b/docs/workflow/AGENTS.md new file mode 100644 index 0000000..44ccca0 --- /dev/null +++ b/docs/workflow/AGENTS.md @@ -0,0 +1,31 @@ +# workflow Agent 指南 + +## 目录职责 + +`docs/workflow/` 存放项目开发流程类 Markdown，是开发顺序、质量门禁、版本控制和文档同步规则的流程入口。 + +## 文件地图 + +```text +workflow/ +├── README.md # 线性总文档：开发流程集合 +└── AGENTS.md # 本目录操作规则 +``` + +## 修改规则 + +- 继承 `docs/AGENTS.md` 的 README 结构契约：H1 后直接进入 `## 字多不看`，再按 `快速导航 -> 完整细粒度目录 -> 使用方式 -> 正文` 排列。 +- 本目录只放流程类文档，不放一次性任务记录、日志、源码快照或私密配置。 +- 新增流程时优先追加到 `README.md`，不新增同级主题 `.md` 文件。 +- 新增流程必须能被执行、检查和复用，避免只写抽象口号。 +- 涉及命令、路径、配置、CI、Git 操作时，必须与仓库当前事实一致。 +- 不在本目录保存密钥、Token、本地账号、真实私有项目配置或一次性日志。 +- 架构、目录、命令或质量门禁发生变化时，同步更新本目录和根 `README.md` / `AGENTS.md`。 +- 不在 README 正文中写 `和其他目录的边界` 或 `维护规则`；维护者规则只写本文件。 +- 不确定项标注 TODO，并说明需要哪个文件或命令输出才能确认。 + +## 验证 + +```bash +make test +``` diff --git a/docs/workflow/README.md b/docs/workflow/README.md new file mode 100644 index 0000000..b1b1a9e --- /dev/null +++ b/docs/workflow/README.md @@ -0,0 +1,52 @@ +# workflow + +## 字多不看 + +- 本目录收敛项目开发流程，回答“从接到任务到提交推送应该怎么做”。 +- 默认流程是：明确目标、读取上下文、制定计划、执行修改、运行门禁、检查差异、控制版本、推送远端、同步文档。 +- 涉及目录、命令、配置、质量门禁或版本控制变化时，必须同步更新对应 README / AGENTS / 索引。 +- 流程要能执行、检查和复用，不写只适合一次性任务的日志。 + +## 快速导航 + +1. [开发流程](#workflow-development-process) - 项目默认开发顺序、检查节点和交付闭环。 + +
+完整细粒度目录（点击展开/收起） + +### 细粒度目录 + +- [1. 开发流程](#workflow-development-process) + +
+ +## 使用方式 + +- 开始任务前，先按本文档确认任务顺序和验收节点。 +- 需要执行 Git、提交或推送时，同时遵循根目录 `AGENTS.md` 中的版本控制规则。 +- 修改流程内容后，运行 `make sync-doc-toc` 和 `make test`。 + +## 正文 + +--- + +
+1. 开发流程 - 默认任务推进顺序、质量门禁和交付闭环。（点击展开/收起） + + + +## 1. 开发流程 + +默认开发流程： + +1. 明确目标：写清楚要做什么、不要做什么、成功标准是什么。 +2. 读取上下文：先看 README、AGENTS、相关目录说明和现有实现。 +3. 制定计划：把任务拆成可验证的小步骤，必要时先给用户确认。 +4. 执行修改：按最小影响面修改文件，不顺手重构无关内容。 +5. 运行门禁：至少运行 `make test`；涉及专项工具时补对应验证命令。 +6. 检查差异：用 `git diff` 确认没有混入临时文件、敏感信息或无关改动。 +7. 控制版本：使用语义清晰的 commit 记录阶段性成果。 +8. 推送远端：默认推送当前 `develop` 分支，并观察 GitHub Actions 结果。 +9. 同步文档：目录、命令、配置、流程变化必须同步 README / AGENTS / 对应索引。 + +
diff --git a/metadata/redirects.yml b/metadata/redirects.yml index acac388..687e514 100644 --- a/metadata/redirects.yml +++ b/metadata/redirects.yml @@ -8,6 +8,8 @@ redirects: to: docs/philosophy/ - from: docs/concepts/philosophy/ to: docs/philosophy/ + - from: Workflow/ + to: docs/workflow/ # Merged concept documents. - from: docs/concepts/思维模型.md diff --git a/metadata/taxonomy.yml b/metadata/taxonomy.yml index b19bd62..b266dd5 100644 --- a/metadata/taxonomy.yml +++ b/metadata/taxonomy.yml @@ -19,6 +19,11 @@ sections: purpose: 新技术、技术栈、优秀 repo、工程范式和工具趋势的短篇研究 entry: docs/research/README.md agent_guide: docs/research/AGENTS.md + workflow: + path: docs/workflow + purpose: 开发流程、质量门禁、版本控制和文档同步的执行顺序 + entry: docs/workflow/README.md + agent_guide: docs/workflow/AGENTS.md references: path: docs/references purpose: 清单、模板、强约束与常见坑 @@ -53,6 +58,7 @@ reading_paths: documents: - AGENTS.md - docs/AGENTS.md + - docs/workflow/README.md#workflow-development-process - docs/getting-started/README.md - docs/getting-started/README.md#vibe-coding-experience - docs/references/README.md#reference-engineering-practice @@ -63,6 +69,7 @@ selection_rules: philosophy: 需要思维模型、底层认知框架、编程哲学或复杂系统描述方法时读取。 references: 需要工程模板、质量门禁、技术栈、常见坑和可执行检查清单时读取。 research: 需要新技术、新 repo、工程趋势和采用前判断时读取。 + workflow: 需要标准开发顺序、质量门禁、版本控制和文档同步流程时读取。 getting-started: 需要从零开始配置网络、Codex CLI、开发环境并完成最小闭环时读取。 documents: @@ -128,6 +135,10 @@ documents: - path: docs/research/README.md#research-harness-engineering title: Harness 工程解析 role: 工程控制、评估器、反馈闭环与 AI 生成系统可靠性 + workflow: + - path: docs/workflow/README.md#workflow-development-process + title: 开发流程 + role: 默认任务推进顺序、质量门禁和交付闭环 top_level: skills: diff --git a/scripts/check-directory-docs.py b/scripts/check-directory-docs.py index 7080e39..0e707bf 100644 --- a/scripts/check-directory-docs.py +++ b/scripts/check-directory-docs.py @@ -23,6 +23,7 @@ REQUIRED_DIRS = [ Path("docs/philosophy"), Path("docs/references"), Path("docs/research"), + Path("docs/workflow"), Path("metadata"), Path("prompts"), Path("scripts"),