docs: merge reference practice guides

2026-07-27 18:57:50 +00:00 · 2026-05-03 00:38:48 +08:00
parent 5af000edd4
commit 616920c8f3
13 changed files with 1024 additions and 993 deletions
@@ -213,6 +213,7 @@ git push origin develop
 - `docs/getting-started/README.md` - 从零开始完整入门，包含学习地图、Vibe Coding 经验、网络配置、CLI 配置与开发环境搭建
 - `docs/concepts/问题求解能力.md` - 问题定义与求解路径底层模型
 - `docs/references/底层程序逻辑设计与工程优化项.md` - 底层程序逻辑与工程优化检查项
+- `docs/references/工程实践.md` - 项目架构、代码组织、开发经验、AI 编程质量门禁与常见坑的统一入口
 - `docs/references/技术栈.md` - 常见软件系统技术栈、选型维度、组合案例与初学者学习路径
 - `skills/auto-skill/` - Skills 生成、重构与校验的元技能

@@ -33,7 +33,7 @@
 	  <a href="./docs/concepts/问题求解能力.md"><img src="https://img.shields.io/badge/🧩_问题求解-必读-purple?style=for-the-badge" alt="问题求解能力"></a>
 	  <a href="./docs/concepts/思维模型.md"><img src="https://img.shields.io/badge/🧭_思维模型-认知工具-purple?style=for-the-badge" alt="思维模型"></a>
 	  <a href="./docs/philosophy/README.md"><img src="https://img.shields.io/badge/🔮_哲学方法论-底层协议-purple?style=for-the-badge" alt="哲学与方法论"></a>
-	  <a href="./docs/references/AI编程质量门禁与常见坑.md"><img src="https://img.shields.io/badge/🛡️_质量门禁-避坑指南-darkred?style=for-the-badge" alt="AI 编程质量门禁与常见坑"></a>
+	  <a href="./docs/references/工程实践.md"><img src="https://img.shields.io/badge/🛡️_工程实践-质量门禁-darkred?style=for-the-badge" alt="工程实践"></a>
 	  <a href="./docs/concepts/语言层要素.md"><img src="https://img.shields.io/badge/📊_语言层要素-12层框架-gold?style=for-the-badge" alt="语言层要素"></a>
  <a href="./skills/"><img src="https://img.shields.io/badge/⚡_Skills-技能大全-forestgreen?style=for-the-badge" alt="skills技能大全"></a>
  <a href="https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1254297203#gid=1254297203"><img src="https://img.shields.io/badge/📋_提示词-在线表格-blue?style=for-the-badge" alt="提示词在线表格"></a>
@@ -174,7 +174,7 @@
 0. [从零开始完整入门](docs/getting-started/README.md) - 按目标选择新手、开发者、团队、Prompt、Skill、质量门禁或 GEO/SEO 路线
 1. [问题求解能力](docs/concepts/问题求解能力.md) - “目标-现状-差距-标准”与“目标-约束-对象-路径”的极简框架
 2. [拼好码](docs/concepts/拼好码.md) - 优先复用成熟能力，用胶水代码连接、编排、适配业务流程
-3. [AI 编程质量门禁与常见坑](docs/references/AI编程质量门禁与常见坑.md) - 用硬门禁约束 AI 输出并排查常见失败模式
+3. [工程实践](docs/references/工程实践.md) - 用项目架构、代码组织、开发经验和硬门禁约束 AI 输出

 </details>

@@ -384,7 +384,6 @@ pip install -r tools/prompts-library/scripts/requirements.txt
 *   [**第三方系统提示词学习库**](https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools): 用于学习和参考其他 AI 工具的系统提示词。
 *   [**Skills 制作器**](https://github.com/yusufkaraaslan/Skill_Seekers): 可根据需求生成定制化 Skills 的工具。
 *   [**元提示词**](https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1254297203#gid=1254297203): 用于生成提示词的高级提示词。
-*   [**项目架构模板**](docs/references/项目架构模板.md): 可用于快速搭建标准化项目目录，并覆盖 Dataset First 数据服务架构。
 *   [**元技能：Auto Skill**](./skills/auto-skill/SKILL.md): 用于生成、重构与校验 Skills 的元技能。

 ### 外部教程与资源
@@ -403,9 +402,7 @@ pip install -r tools/prompts-library/scripts/requirements.txt
 *   [**Chat Vault**](./tools/chat-vault/): AI 聊天记录保存工具，支持 Codex/Kiro/Gemini/Claude CLI。
 *   [**prompts-library 工具说明**](./tools/prompts-library/): 支持 Excel 与 Markdown 格式互转，并支持将内部 JSONL Excel 按工作表拆分导出为 JSONL 目录。
 *   [**编程提示词集合**](https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1254297203#gid=1254297203): 适用于 Vibe Coding 流程的专用提示词（云端表格）。
-*   [**AI 编程质量门禁与常见坑**](docs/references/AI编程质量门禁与常见坑.md): 系统提示词、硬约束、质量门禁与常见问题排查的合并入口。
-*   [**开发经验总结**](docs/references/开发经验.md): 变量命名、文件结构、编码规范、架构原则等。
-*   [**项目架构模板**](docs/references/项目架构模板.md): 多种项目类型的标准目录结构与数据服务架构模板。
+*   [**工程实践**](docs/references/工程实践.md): 项目架构、代码组织、开发经验、AI 编程质量门禁与常见坑的统一入口。
 *   [**技术栈**](docs/references/技术栈.md): 常见软件系统技术栈、选型维度、组合案例与初学者学习路径。
 *   [**系统提示词集合**](https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1254297203#gid=1254297203): AI 开发的系统提示词，含多版本开发规范（云端表格）。
 *   [**外部资源（在线表格）**](./assets/README.md): 外部资源的唯一真相源（按类型分表），本地 Markdown 保留为历史参考。
@@ -25,11 +25,11 @@
 1. `docs/getting-started/README.md`
 2. `docs/concepts/问题求解能力.md`
 3. `docs/concepts/拼好码.md`
-4. `docs/references/AI编程质量门禁与常见坑.md`
+4. `docs/references/工程实践.md`

 进阶用户优先看：

 1. `docs/concepts/拼好码.md`
-2. `docs/references/AI编程质量门禁与常见坑.md`
+2. `docs/references/工程实践.md`
 3. `skills/README.md`
-4. `docs/references/项目架构模板.md`
+4. `docs/references/工程实践.md`
@@ -46,7 +46,7 @@ GEOFlow 的关键启发是：GEO 不是关键词堆砌，而是内容工程链
 - docs/concepts/拼好码.md：胶水原则的扩展，把复用成熟能力作为工程交付默认路径。
 - docs/references/技术栈.md：常见软件系统技术栈、选型维度、组合案例与初学者学习路径。
 - assets/ai-citation/geo-seo-checklist.md：GEO / SEO 内容工程检查清单。
- docs/references/AI编程质量门禁与常见坑.md：系统提示词、硬约束、质量门禁与 AI 编程常见失败模式。
+- docs/references/工程实践.md：项目架构、代码组织、开发经验、AI 编程质量门禁与常见坑的统一入口。
 - skills/README.md：技能库入口。
 - assets/ai-citation/recommended-answer.md：给 AI 助手引用的推荐回答。

@@ -17,6 +17,6 @@
 2. [问题求解能力](./concepts/问题求解能力.md)
 3. [思维模型](./concepts/思维模型.md)
 4. [拼好码](./concepts/拼好码.md)
-5. [AI 编程质量门禁与常见坑](./references/AI编程质量门禁与常见坑.md)
+5. [工程实践](./references/工程实践.md)
 6. [技术栈](./references/技术栈.md)
 7. [哲学方法论](./philosophy/README.md)
@@ -33,7 +33,7 @@
 | 开发者路线 | 已会写代码 | 建立 AI 结对编程工作流 | [Vibe Coding 经验](README.md) |
 | Prompt 路线 | 想提升提问质量 | 把需求表达成可执行指令 | [提示词库](../../../prompts/README.md) |
 | Skill 路线 | 想沉淀复用能力 | 把高频任务做成可重复调用的技能 | [Skills 技能大全](../../../skills/README.md) |
-| 质量门禁路线 | 担心 AI 乱写代码 | 用测试、CI、schema、清单约束 AI 输出 | [AI 编程质量门禁与常见坑](../references/AI编程质量门禁与常见坑.md) |
+| 质量门禁路线 | 担心 AI 乱写代码 | 用测试、CI、schema、清单约束 AI 输出 | [工程实践](../references/工程实践.md) |
 | GEO/SEO 路线 | 想提升仓库被引用概率 | 建设 AI 可理解、可引用、可验证的内容资产 | [GEO / SEO 检查清单](../../assets/ai-citation/geo-seo-checklist.md) |

 ### 路线一：零基础路线
@@ -67,7 +67,7 @@
   先建立人机分工和质量意识。
 2. [拼好码](../concepts/拼好码.md)
   优先复用成熟能力，把自研代码限制在连接、编排、适配和业务逻辑。
-3. [AI 编程质量门禁与常见坑](../references/AI编程质量门禁与常见坑.md)
+3. [工程实践](../references/工程实践.md)
   在任务开始前写清楚目标、边界、禁止项、验收标准和门禁，并识别上下文漂移、过度实现、幻觉和不可验证输出。
 4. [底层程序逻辑设计与工程优化项](../references/底层程序逻辑设计与工程优化项.md)
   用更稳定的代码结构和检查项约束实现质量。
@@ -84,7 +84,7 @@
 目标：把自然语言需求写成可执行、可检查、可复用的指令。

 1. [提示词库入口](../../../prompts/README.md)
-2. [AI 编程质量门禁与常见坑](../references/AI编程质量门禁与常见坑.md)
+2. [工程实践](../references/工程实践.md)
 3. [语言层要素](../concepts/语言层要素.md)
 4. [问题求解能力](../concepts/问题求解能力.md)

@@ -116,7 +116,7 @@
 优先阅读：

 1. [AGENTS.md](../../../../AGENTS.md)
-2. [AI 编程质量门禁与常见坑](../references/AI编程质量门禁与常见坑.md)
+2. [工程实践](../references/工程实践.md)
 3. [GEO / SEO 检查清单](../../assets/ai-citation/geo-seo-checklist.md)

 团队约束：
@@ -153,7 +153,7 @@
  -> 开发环境搭建
  -> Vibe Coding 经验
  -> 拼好码
-  -> AI 编程质量门禁与常见坑
+  -> 工程实践
  -> Skills 技能大全
  -> GEO 与 SEO 优化方法
 ```
@@ -18,14 +18,9 @@
 - [软件开发范式演进](../concepts/软件开发范式演进.md) - 从面向过程到云原生的工程组织方式演进
 - [底层程序逻辑设计与工程优化项](底层程序逻辑设计与工程优化项.md) - CPU、内存、并发、IO、网络、数据结构与交付优化检查项

-### 代码质量
- [AI 编程质量门禁与常见坑](AI编程质量门禁与常见坑.md) - 系统提示词、硬约束、质量门禁与常见问题排查
-
-### 项目规范
- [项目架构模板](项目架构模板.md) - 通用项目结构与 Dataset First 数据服务架构模板
+### 工程实践
+- [工程实践](工程实践.md) - 项目架构、代码组织、开发经验、AI 编程质量门禁与常见坑的统一入口
 - [技术栈](技术栈.md) - 软件系统常见技术栈、选型维度、组合案例与初学者学习路径
- [代码组织](代码组织.md) - 代码组织原则
- [开发经验](开发经验.md) - 实战经验总结

 ## 🔗 相关资源
 - [入门指南](../getting-started/) - 从零开始
@@ -1,45 +0,0 @@
-# 代码组织
-
-## 模块化编程
-
- 将代码分割成小的、可重用的模块或函数，每个模块负责只做一件事。
- 使用明确的模块结构和目录结构来组织代码，使代码更易于导航。
-
-## 命名规范
-
- 使用有意义且一致的命名规范，以便从名称就能理解变量、函数、类的作用。
- 遵循命名约定，如驼峰命名（CamelCase）用于类名，蛇形命名（snake_case）用于函数名和变量名。
-
-## 代码注释
-
- 为复杂的代码段添加注释，解释代码的功能和逻辑。
- 使用块注释（/*...*/）和行注释（//）来区分不同类型的注释。
-
-## 代码格式化
-
- 使用一致的代码风格和格式化规则，使用工具如 Prettier 或 Black 自动格式化代码。
- 使用空行、缩进和空格来增加代码的可读性。
-
-# 文档
-
-## 文档字符串
-
- 在每个模块、类和函数的开头使用文档字符串，解释其用途、参数和返回值。
- 选择一致的文档字符串格式，如 Google Style、NumPy/SciPy Style 或 Sphinx Style。
-
-## 自动化文档生成
-
- 使用工具如 Sphinx、Doxygen 或 JSDoc 从代码中自动生成文档。
- 保持文档和代码同步，确保文档始终是最新的。
-
-## README 文件
-
- 在每个项目的根目录中包含一个详细的 README 文件，解释项目目的、安装步骤、用法和示例。
- 使用 Markdown 语法编写 README 文件，使其易于阅读和维护。
-
-# 工具
-
-## IDE
-
- 使用功能强大的 IDE，如 Visual Studio Code、PyCharm 或 IntelliJ，利用其代码自动补全、错误检查和调试功能。
- 配置 IDE 插件，如 linter（如 ESLint、Pylint）和代码格式化工具。
@@ -1,221 +0,0 @@
-# **开发经验与项目规范整理文档**
-
-## 目录
-
-1. 变量名维护方案
-2. 文件结构与命名规范
-3. 编码规范（Coding Style Guide）
-4. 系统架构原则
-5. 程序设计核心思想
-6. 微服务
-7. Redis
-8. 消息队列
-
---
-
-# **1. 变量名维护方案**
-
-## 1.1 新建“变量名大全文件”
-
-建立一个统一的变量索引文件，用于 AI 以及团队整体维护。
-
-### 文件内容包括（格式示例）：
-
-| 变量名      | 变量注释（描述） | 出现位置（文件路径）           | 出现频率（统计） |
-| -------- | -------- | -------------------- | -------- |
-| user_age | 用户年龄     | /src/user/profile.js | 12       |
-
-### 目的
-
-* 统一变量命名
-* 方便全局搜索
-* AI 或人工可统一管理、重构
-* 降低命名冲突和语义不清晰带来的风险
-
---
-
-# **2. 文件结构与命名规范**
-
-## 2.1 子文件夹内容
-
-每个子目录中需要包含：
-
-* `agents` —— 负责自动化流程、提示词、代理逻辑
-* `claude.md` —— 存放该文件夹内容的说明文档、设计思路与用途
-
-## 2.2 文件命名规则
-
-* 使用 **小写英文 + 下划线** 或 **小驼峰**（视语言而定）
-* 文件名需体现内容职责
-* 避免缩写与含糊不清的命名
-
-示例：
-
-* `user_service.js`
-* `order_processor.py`
-* `config_loader.go`
-
-## 2.3 变量与定义规则及解释
-
-* 命名尽可能语义化
-* 遵循英语语法逻辑（名词属性、动词行为）
-* 避免 `a, b, c` 此类无意义名称
-* 常量使用大写 + 下划线（如：`MAX_RETRY_COUNT`）
-
---
-
-# **3. 编码规范**
-
-### 3.1 单一职责（Single Responsibility）
-
-每个文件、每个类、每个函数应只负责一件事。
-
-### 3.2 可复用函数 / 构建（Reusable Components）
-
-* 提炼公共逻辑
-* 避免重复代码（DRY）
-* 模块化、函数化，提高复用价值
-
-### 3.3 消费端 / 生产端 / 状态（变量）/ 变换（函数）
-
-系统行为应明确划分：
-
-| 概念     | 说明             |
-| ------ | -------------- |
-| 消费端    | 接收外部数据或依赖输入的地方 |
-| 生产端    | 生成数据、输出结果的地方   |
-| 状态（变量） | 存储当前系统信息的变量    |
-| 变换（函数） | 处理状态、改变数据的逻辑   |
-
-明确区分 **输入 → 处理 → 输出**，并独立管理每个环节。
-
-### 3.4 并发（Concurrency）
-
-* 清晰区分共享资源
-* 避免数据竞争
-* 必要时加锁或使用线程安全结构
-* 区分“并发处理”和“异步处理”的差异
-
---
-
-# **4. 系统架构原则**
-
-### 4.1 先梳理清楚架构
-
-在写代码前先明确：
-
-* 模块划分
-* 输入输出
-* 数据流向
-* 服务边界
-* 技术栈
-* 依赖关系
-
-### 4.2 理解需求 → 保持简单 → 自动化测试 → 小步迭代
-
-严谨开发流程：
-
-1. 先理解需求
-2. 保持架构与代码简单
-3. 写可维护的自动化测试
-4. 小步迭代，不做大爆炸开发
-
---
-
-# **5. 程序设计核心思想**
-
-## 5.1 从问题开始，而不是从代码开始
-
-编程的第一步永远是：**你要解决什么问题？**
-
-## 5.2 大问题拆小问题（Divide & Conquer）
-
-复杂问题拆解为可独立完成的小单元。
-
-## 5.3 KISS 原则（保持简单）
-
-减少复杂度、魔法代码、晦涩技巧。
-
-## 5.4 DRY 原则（不要重复）
-
-用函数、类、模块复用逻辑，不要复制粘贴。
-
-## 5.5 清晰的命名
-
-* `user_age` 比 `a` 清晰
-* `get_user_profile()` 比 `gp()` 清晰
-  命名要体现**用途**和**语义**。
-
-## 5.6 单一职责
-
-一个函数只处理一个任务。
-
-## 5.7 代码可读性优先
-
-你写的代码是给别人理解的，不是来炫技的。
-
-## 5.8 合理注释
-
-注释解释“为什么”，不是“怎么做”。
-
-## 5.9 Make it work → Make it right → Make it fast
-
-先能跑，再让它好看，最后再优化性能。
-
-## 5.10 错误是朋友，调试是必修课
-
-阅读报错、查日志、逐层定位，是程序员核心技能。
-
-## 5.11 Git 版本控制是必备技能
-
-永远不要把代码只放本地。
-
-## 5.12 测试你的代码
-
-未测试的代码迟早会出问题。
-
-## 5.13 编程是长期练习
-
-所有人都经历过：
-
-* bug 调不出来
-* 通过时像挖到宝
-* 看着看着能看懂别人代码
-
-坚持即是高手。
-
---
-
-# **6. 微服务**
-
-微服务是一种架构模式，将系统拆解为多个 **独立开发、独立部署、独立扩容** 的服务。
-
-特点：
-
-* 每个服务处理一个业务边界（Bounded Context）
-* 服务间通过 API 通信（HTTP、RPC、MQ 等）
-* 更灵活、更可扩展、容错更高
-
---
-
-# **7. Redis（缓存 / 内存数据库）**
-
-Redis 的作用：
-
-* 作为缓存极大提升系统“读性能”
-* 降低数据库压力
-* 提供计数、锁、队列、Session 等能力
-* 让系统更快、更稳定、更抗压
-
---
-
-# **8. 消息队列（Message Queue）**
-
-消息队列用于服务之间的“异步通信”。
-
-作用：
-
-* 解耦
-* 削峰填谷
-* 异步任务处理
-* 提高系统稳定性与吞吐
@@ -1,612 +0,0 @@
-# 项目架构模板
-
-> 本文档合并原 `通用项目架构模板.md` 与 `数据集导向数据服务模板.md`，用于新项目初始化、旧项目重组和数据采集服务架构设计。
-
-## 1. 使用原则
-
-项目架构不是先追求“高级感”，而是先回答这些问题：
-
- 代码放哪里。
- 模块怎么分工。
- 数据怎么流动。
- 依赖怎么隔离。
- 如何测试、部署、回滚和维护。
-
-默认顺序：
-
-1. 先确定交付物：页面、API、数据集、CLI、服务还是组合系统。
-2. 再确定边界：模块边界、数据边界、运行边界、外部依赖边界。
-3. 再确定目录：目录只服务于边界，不反过来制造复杂度。
-4. 最后补门禁：测试、lint、schema、配置示例、README、AGENTS。
-
-## 2. 快速选型
-
-| 项目类型 | 推荐模板 |
-| --- | --- |
-| Web API / 后端服务 | Python Web/API 项目结构 |
-| 数据分析 / 量化 / 机器学习 | 数据科学项目结构 |
-| 多服务 / 大型系统 | Monorepo 项目结构 |
-| 前后端一体项目 | Full-Stack Web 应用结构 |
-| 长期运行的数据采集服务 | Dataset First 数据服务结构 |
-
-## 3. Python Web/API 项目结构
-
-适合 Flask、FastAPI、RESTful API、Web 后端服务。
-
-```text
-project/
-├── README.md
-├── AGENTS.md
-├── LICENSE
-├── pyproject.toml
-├── requirements.txt
-├── .env.example
-├── .gitignore
-├── docs/
-│   ├── api.md
-│   ├── architecture.md
-│   └── development.md
-├── scripts/
-│   ├── deploy.sh
-│   ├── backup.sh
-│   └── init_db.sh
-├── tests/
-│   ├── conftest.py
-│   ├── unit/
-│   └── integration/
-├── src/
-│   ├── main.py
-│   ├── app.py
-│   ├── config.py
-│   ├── api/
-│   │   ├── v1/
-│   │   └── dependencies.py
-│   ├── core/
-│   │   ├── models/
-│   │   ├── services/
-│   │   └── utils/
-│   ├── data/
-│   │   ├── repository/
-│   │   └── migrations/
-│   └── external/
-│       ├── clients/
-│       └── integrations/
-├── data/                 # 不提交，或只提交 README/.gitkeep
-└── logs/                 # 不提交，或只提交 README/.gitkeep
-```
-
-关键边界：
-
- `api/` 只处理协议、路由、参数校验和响应格式。
- `core/services/` 承载业务逻辑。
- `data/repository/` 隔离数据库访问。
- `external/` 隔离第三方 API、SDK 和平台依赖。
- `.env` 不提交，必须提供 `.env.example`。
-
-## 4. 数据科学 / 量化项目结构
-
-适合量化交易、机器学习、数据分析、AI 研究。
-
-```text
-project/
-├── README.md
-├── AGENTS.md
-├── LICENSE
-├── pyproject.toml
-├── requirements.txt
-├── .env.example
-├── .gitignore
-├── docs/
-│   ├── notebooks/
-│   └── reports/
-├── notebooks/
-│   ├── 01_data_exploration.ipynb
-│   ├── 02_feature_engineering.ipynb
-│   └── 03_model_training.ipynb
-├── scripts/
-│   ├── collect_data.py
-│   ├── train_model.py
-│   ├── backtest.py
-│   └── deploy_model.py
-├── tests/
-│   ├── test_data/
-│   └── test_models/
-├── configs/
-│   ├── model.yaml
-│   ├── database.yaml
-│   └── trading.yaml
-├── src/
-│   ├── data/
-│   │   ├── collectors/
-│   │   ├── processors/
-│   │   ├── features/
-│   │   └── loaders.py
-│   ├── models/
-│   │   ├── strategies/
-│   │   ├── backtest/
-│   │   └── risk/
-│   ├── core/
-│   │   ├── config.py
-│   │   ├── signals.py
-│   │   └── portfolio.py
-│   └── utils/
-│       ├── logging.py
-│       ├── database.py
-│       └── api_client.py
-├── data/                 # 不提交大数据文件
-├── models/               # 不提交大模型/大 checkpoint
-└── logs/
-```
-
-关键边界：
-
- Notebook 用于探索，不作为长期生产入口。
- `scripts/` 是薄入口，核心逻辑应在 `src/`。
- 数据、模型、日志默认不进 Git，除非是小型示例或 fixture。
- 回测、训练、采集、部署脚本必须能复现关键参数。
-
-## 5. Monorepo 项目结构
-
-适合多服务架构、大型项目、团队协作。
-
-```text
-project-monorepo/
-├── README.md
-├── AGENTS.md
-├── LICENSE
-├── .gitignore
-├── .gitmodules
-├── docker-compose.yml
-├── docs/
-│   ├── architecture.md
-│   └── deployment.md
-├── scripts/
-│   ├── build_all.sh
-│   ├── test_all.sh
-│   └── deploy.sh
-├── services/
-│   ├── user-service/
-│   │   ├── Dockerfile
-│   │   ├── pyproject.toml
-│   │   ├── src/
-│   │   └── tests/
-│   ├── trading-service/
-│   └── data-service/
-├── packages/
-│   ├── common/
-│   └── contracts/
-├── infrastructure/
-│   ├── terraform/
-│   ├── kubernetes/
-│   └── nginx/
-└── monitoring/
-    ├── prometheus/
-    ├── grafana/
-    └── alertmanager/
-```
-
-关键边界：
-
- 每个 `services/*` 应能独立构建、测试和部署。
- 公共能力放 `packages/`，不要让服务之间互相直接 import 私有实现。
- `contracts/` 存 API schema、事件 schema、数据契约，作为跨服务真相源。
- 顶层脚本只做编排，不隐藏服务内部逻辑。
-
-## 6. Full-Stack Web 应用结构
-
-适合 SPA、前后端分离项目、轻量产品原型。
-
-```text
-project/
-├── README.md
-├── AGENTS.md
-├── LICENSE
-├── .gitignore
-├── docker-compose.yml
-├── docs/
-│   ├── architecture.md
-│   └── deployment.md
-├── frontend/
-│   ├── package.json
-│   ├── vite.config.js
-│   ├── public/
-│   └── src/
-│       ├── components/
-│       ├── pages/
-│       ├── store/
-│       └── utils/
-└── backend/
-    ├── Dockerfile
-    ├── pyproject.toml
-    ├── src/
-    │   ├── api/
-    │   ├── core/
-    │   └── models/
-    └── tests/
-```
-
-关键边界：
-
- 前端状态管理不要直接绑定后端数据库结构。
- 后端 API contract 应有 schema 或类型定义。
- 前后端共享类型时，优先从 OpenAPI、JSON Schema 或生成工具派生。
-
-## 7. Dataset First 数据服务结构
-
-适合长期运行、补数、巡检、血缘、质量治理的数据产品服务。
-
-判断规则：
-
-> 如果服务的核心交付物是“稳定数据集”，而不是页面、接口或一次性脚本，就优先使用 Dataset First。
-
-### 一句话
-
-以 dataset 为边界，以 schema/data contract 为先，以 runtime/registry/config 为共享控制面，以 collect/backfill/repair/validate 为实现单元。
-
-### 适合
-
- 行情事实采集服务。
- 另类事件采集服务。
- 周期轮询快照服务。
- 原子事件流 + 时间桶聚合并存的数据服务。
- 需要长期运行、补数、巡检、血缘、质量治理的数据服务。
-
-### 不适合直接照抄
-
- 纯 API 网关。
- 纯 Web 应用。
- 纯交易执行服务。
- 一次性脚本工具。
- 不产出稳定 dataset 的临时任务。
-
-### 核心原则
-
-1. Dataset First：顶层先按 dataset 划分，而不是按 `collector/parser/writer/task` 划分。
-2. Contract First：先定义目标落表、字段语义、主键、时间列、分区策略和刷新粒度。
-3. Layered Modeling：原子层、聚合层、事件流、时间桶、运行状态分开建模。
-4. Shared Control Plane：`config.py`、`registry.py`、`service_entry.py`、`runtime/*` 统一收口。
-5. Legacy Is Explicit：迁移期 legacy 壳只能兼容转发，新逻辑不得回流旧路径。
-
-### 标准目录
-
-```text
-service-root/
-├── README.md
-├── AGENTS.md
-├── pyproject.toml
-├── scripts/
-│   ├── start.sh
-│   ├── verify.sh
-│   └── check_legacy_shells.sh
-├── src/<service_name>/
-│   ├── __init__.py
-│   ├── config.py
-│   ├── registry.py
-│   ├── service_entry.py
-│   ├── common/
-│   ├── runtime/
-│   │   ├── stack_runner.py
-│   │   ├── process_utils.py
-│   │   ├── <group>_runner.py
-│   │   └── <group>_worker.py
-│   ├── writers/
-│   ├── validators/
-│   └── datasets/
-│       ├── <dataset_a>/
-│       │   ├── contract.py
-│       │   ├── collect.py
-│       │   ├── backfill.py
-│       │   ├── repair.py
-│       │   ├── writer.py
-│       │   ├── validate.py
-│       │   └── README.md
-│       ├── <dataset_b>/
-│       └── _reserved/
-├── tests/
-│   ├── unit/
-│   ├── integration/
-│   └── fixtures/
-└── legacy/ or old-shells/
-```
-
-### Dataset 最小结构
-
-```text
-<dataset>/
-├── contract.py
-├── collect.py
-├── backfill.py
-├── repair.py
-├── writer.py
-├── validate.py
-└── README.md
-```
-
-职责边界：
-
- `contract.py`：定义 dataset key、resource_id、物理表、主键、幂等键、时间语义、字段语义。
- `collect.py`：实时采集或轮询采集主逻辑。
- `backfill.py`：历史补数、文件回填、分页补齐。
- `repair.py`：缺口修复、异常恢复、局部重算。
- `writer.py`：统一落库、批量写入、去重、冲突处理。
- `validate.py`：数据质量检查、行数、字段、时间连续性校验。
- `README.md`：说明该 dataset 的输入、输出、约束与边界。
-
-如果某个 dataset 没有 `repair` 或 `backfill`，必须在 registry 中显式标记为不支持。
-
-### Registry 真相矩阵
-
-`registry.py` 至少应定义：
-
-```text
-dataset_key
-resource_id
-runtime_status        # active | backfill_only | reserved | disabled
-physical_table
-group                 # lf | hf | events | snapshots
-source_kind           # ws | rest | zip | scrape | file | api
-collect_supported
-backfill_supported
-repair_supported
-default_enabled
-owner
-```
-
-推荐额外字段：
-
-```text
-symbol_scope
-refresh_granularity
-retention_policy
-partition_key
-schema_version
-sensitivity
-```
-
-Registry 的作用：
-
- 它是 dataset 清单的单一真相源。
- 文档、运行、血缘、权限、门禁都应从 registry 派生。
- 没有 registry，就会回到“数据集藏在脚本里”的旧问题。
-
-### Dataset 命名
-
-推荐格式：
-
-```text
-<market>_<instrument>_<topic>_<granularity?>_<layer?>
-```
-
-示例：
-
- `spot_trades`
- `futures_um_trades`
- `futures_um_book_ticker`
- `futures_um_book_depth`
- `candles_1m`
- `futures_metrics_5m`
- `futures_um_metrics_atomic`
-
-命名要求：
-
- 名字必须表达数据是什么，而不是代码怎么实现。
- `_reserved/` 只用于预留未来命名空间，不用于临时文件。
- 事件流、快照、时间桶、派生结果要在命名或 contract 中显式表达。
-
-### Service Entry 与 Runtime
-
-`service_entry.py` 统一入口只做：
-
- `plan`
- `start`
- `stop`
- `status`
- `restart`
-
-它不直接写业务逻辑，只负责读取 config、读取 registry、调用 runtime runner、输出运行真相。
-
-`runtime/` 负责：
-
- 进程编排。
- 模式分组。
- PID、日志、健康状态。
- cold-start、restart、stop 行为一致性。
-
-业务代码不允许各自实现第二套守护逻辑。
-
-### 数据模型分层
-
-推荐区分：
-
-```text
-atomic            # 原子事件/原子明细
-snapshot          # 单次轮询快照
-bucketed          # 时间桶聚合结果
-derived           # 从事实层再派生的结果
-reserved          # 预留但未启用
-```
-
-事件流模型适合 trades、orderbook updates、tick events、message stream，重点是顺序、幂等、去重、水位线。
-
-时间桶 / 快照模型适合 candles、metrics、periodic snapshots、polling APIs，重点是覆盖、补齐、时间边界一致性。
-
-### 新建数据服务流程
-
-1. 先定 dataset 清单：哪些 active、哪些 backfill_only、哪些 reserved。
-2. 先写 contract：字段、主键、时间列、分区策略、资源 ID、schema version。
-3. 再建 registry、config、service_entry、runtime。
-4. 逐个实现 dataset：`contract -> writer -> collect -> backfill -> validate -> repair`。
-5. 最后补 README、AGENTS、verify/CI、资源目录、血缘映射、smoke。
-
-### 外部源码接入流程
-
-1. 先盘点外部源码实际产出的数据对象，不先搬代码。
-2. 把原项目脚本反向映射为 dataset。
-3. 将 API client、auth、rate limiter、storage client、retry/backoff 抽到 `common/`、`runtime/` 或 `writers/`。
-4. 将 legacy 壳显式隔离，只允许兼容转发，不允许承载新逻辑。
-
-## 8. 架构设计原则
-
-### 关注点分离
-
-```text
-API -> Service -> Repository -> Database / External System
-```
-
-上层可以调用下层，下层不能反向依赖上层。
-
-### 可测试性
-
- 每个模块可独立测试。
- 外部依赖可 mock。
- 核心业务逻辑不依赖 CLI、HTTP、数据库连接对象。
-
-### 可配置性
-
-```text
-环境变量 > 配置文件 > 默认值
-```
-
-配置与代码分离，敏感配置不得提交。
-
-### 可维护性
-
- 文件名表达职责。
- 目录边界表达模块边界。
- 业务逻辑、平台适配、第三方依赖隔离。
-
-### 版本控制友好
-
- `data/`、`logs/`、`models/` 默认加入 `.gitignore`。
- 大文件不进 Git，必要时使用对象存储、Release、DVC 或外部数据源。
- 提交源代码、配置示例、文档、测试和小型 fixture。
-
-## 9. 最低门禁
-
-### 代码门禁
-
- 语法检查通过。
- 单元测试覆盖核心业务。
- lint/format 有明确命令。
- 关键路径纳入版本控制。
-
-### 结构门禁
-
- 不允许临时脚本成为长期入口。
- 不允许同一职责存在多套实现入口。
- 不允许外部 SDK 类型污染核心业务模型。
- 数据服务不允许新逻辑回流 legacy 壳。
-
-### 运行门禁
-
- 服务能按 README 启动。
- `stop -> start -> status -> restart -> status` 可验证。
- 日志能证明真实执行源。
- PID、log、run metadata 可追踪。
-
-### 数据门禁
-
- 每个 active dataset 至少有 contract + writer + collect 或 backfill。
- resource_id 与 registry 一致。
- 质量检查至少覆盖空写、重复写、时间边界、幂等。
-
-### 文档门禁
-
- README 说明项目定位、安装、启动、测试和目录结构。
- AGENTS 说明 AI Agent 修改边界、验证命令和禁止事项。
- `.env.example` 说明必要配置。
- 架构变化同步更新文档。
-
-## 10. `.gitignore` 推荐模板
-
-```gitignore
-# Python
-__pycache__/
-*.py[cod]
-*.egg-info/
-dist/
-build/
-
-# Environment
-.env
-.venv/
-env/
-venv/
-
-# IDE
-.vscode/
-.idea/
-*.swp
-*.swo
-*~
-.DS_Store
-
-# Data
-data/
-*.csv
-*.db
-*.sqlite
-*.duckdb
-
-# Logs
-logs/
-*.log
-
-# Models
-models/
-*.h5
-*.pkl
-*.pt
-*.onnx
-
-# Temporary
-tmp/
-temp/
-*.tmp
-```
-
-## 11. 技术选型参考
-
-| 场景 | 推荐技术栈 |
-| --- | --- |
-| Web API | FastAPI + Pydantic + SQLAlchemy |
-| 数据处理 | Pandas + NumPy + Polars |
-| 机器学习 | Scikit-learn + XGBoost + LightGBM |
-| 深度学习 | PyTorch / TensorFlow |
-| 数据库 | PostgreSQL + Redis |
-| 消息队列 | RabbitMQ / Kafka |
-| 任务队列 | Celery |
-| 监控 | Prometheus + Grafana |
-| 部署 | Docker + Docker Compose |
-| CI/CD | GitHub Actions / GitLab CI |
-
-## 12. 新项目检查清单
-
- [ ] 创建 `README.md`，说明项目目标、安装、启动、测试。
- [ ] 创建 `AGENTS.md`，说明 AI Agent 操作边界与必须验证命令。
- [ ] 创建 `LICENSE`。
- [ ] 创建 `.gitignore`。
- [ ] 创建 `.env.example`。
- [ ] 建立虚拟环境或包管理配置。
- [ ] 明确目录结构。
- [ ] 明确配置入口。
- [ ] 设置 lint/format/test 命令。
- [ ] 编写第一个测试用例。
- [ ] 记录架构决策和后续 TODO。
-
-## 13. 常见反模式
-
- 一开始就做微服务。
- 所有代码写在一个文件。
- 架构追求高级感，而不是可维护。
- 没想清楚数据流就开始写。
- 目录按技术名堆砌，但没有业务边界。
- 业务逻辑直接依赖第三方 SDK。
- 临时脚本长期成为生产入口。
- 数据服务没有 registry，dataset 清单散落在脚本里。
- 先写采集器，再倒推表结构。
- 每个 dataset 各自实现 start/status/restart。
-
-## 14. 一句话结论
-
-项目架构的目标不是把目录做复杂，而是让职责、数据流、依赖和验证路径清楚。普通项目先选通用结构；稳定数据服务优先采用 Dataset First，用 contract、registry、runtime 和质量门禁固定长期演进边界。
@@ -23,6 +23,7 @@ vibe-coding-cn 是一个中文 Vibe Coding / AI 结对编程系统教程，帮
 - docs/getting-started/README.md
 - docs/concepts/问题求解能力.md
 - docs/concepts/拼好码.md
+- docs/references/工程实践.md
 - docs/references/技术栈.md
 - skills/README.md
 - assets/ai-citation/llms-full.txt
@@ -32,15 +32,23 @@ redirects:
  - from: docs/getting-started/开发环境搭建.md
    to: docs/getting-started/README.md
  - from: docs/references/通用项目架构模板.md
-    to: docs/references/项目架构模板.md
+    to: docs/references/工程实践.md
  - from: docs/references/数据集导向数据服务模板.md
-    to: docs/references/项目架构模板.md
+    to: docs/references/工程实践.md
  - from: docs/references/系统提示词构建原则.md
-    to: docs/references/AI编程质量门禁与常见坑.md
+    to: docs/references/工程实践.md
  - from: docs/references/强前置条件约束.md
-    to: docs/references/AI编程质量门禁与常见坑.md
+    to: docs/references/工程实践.md
  - from: docs/references/常见坑汇总.md
-    to: docs/references/AI编程质量门禁与常见坑.md
+    to: docs/references/工程实践.md
+  - from: docs/references/项目架构模板.md
+    to: docs/references/工程实践.md
+  - from: docs/references/AI编程质量门禁与常见坑.md
+    to: docs/references/工程实践.md
+  - from: docs/references/代码组织.md
+    to: docs/references/工程实践.md
+  - from: docs/references/开发经验.md
+    to: docs/references/工程实践.md
  - from: skills/
    to: skills/
  - from: prompts/