mirror of
https://github.com/tradecatlabs/vibe-coding-cn.git
synced 2026-08-06 23:57:46 +00:00
docs: standardize docs readme blocks
This commit is contained in:
tukuaiai
+17
-27
@@ -5,15 +5,16 @@
|
||||
|
||||
> `references/` 是工程实践、技术栈、模板、清单、质量门禁和可复用经验的线性手册。
|
||||
|
||||
## 核心摘要
|
||||
## 字多不看
|
||||
|
||||
> 生成规则：本文件由 `docs/references/sources/` 按文件名顺序拼接生成；请修改源片段后运行 `make sync-reference-readme`，不要直接编辑总文档主体。
|
||||
|
||||
- 本目录回答“具体工程怎么组织、怎么选技术、怎么设置硬门禁”。
|
||||
- 它承载稳定、可执行、可检查、可复用的工程参考资料。
|
||||
- 本 README 提供稳定锚点和细粒度目录，作为工程参考资料的统一入口。
|
||||
- 先看“工程实践”，获得项目架构、代码组织、开发经验、质量门禁和常见坑。
|
||||
- 再看“技术栈”，完成技术选型、组合案例判断和初学者学习路径设计。
|
||||
- 长文档优先走快速导航；需要完整索引时再展开细粒度目录。
|
||||
|
||||
## 常用入口
|
||||
## 快速导航
|
||||
|
||||
| 目标 | 直接跳转 |
|
||||
|:---|:---|
|
||||
@@ -26,26 +27,6 @@
|
||||
| 技术栈怎么选 | [如何选择技术栈](#tech-stack-selection) |
|
||||
| 初学者先学什么 | [初学者应该学什么技术栈](#reference-technology-stack-十五初学者应该学什么技术栈) |
|
||||
|
||||
## 总目录
|
||||
|
||||
1. [工程实践](#reference-engineering-practice) - 项目架构、代码组织、开发经验、质量门禁与常见坑。
|
||||
2. [技术栈](#reference-technology-stack) - 技术栈选型、组合案例与学习路径。
|
||||
|
||||
## 折叠块语法
|
||||
|
||||
长目录统一使用 `details + summary`，常用入口放在折叠块外，完整细粒度目录放在折叠块内。
|
||||
|
||||
```md
|
||||
<details>
|
||||
<summary><strong>完整细粒度目录（点击展开/收起）</strong></summary>
|
||||
|
||||
### 细粒度目录
|
||||
|
||||
- [章节](#stable-anchor)
|
||||
|
||||
</details>
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary><strong>完整细粒度目录（点击展开/收起）</strong></summary>
|
||||
|
||||
@@ -360,16 +341,25 @@
|
||||
|
||||
</details>
|
||||
|
||||
## 和其他目录的边界
|
||||
## 使用方式
|
||||
|
||||
- 先从 [工程实践](#reference-engineering-practice) 判断项目结构、代码组织、质量门禁和常见坑。
|
||||
- 再从 [技术栈](#reference-technology-stack) 判断技术选型、组合案例和学习路径。
|
||||
- 只查具体问题时，优先使用上方“快速导航”和细粒度目录。
|
||||
- 本 README 是生成文件；新增或调整正文时先改 `docs/references/sources/`。
|
||||
|
||||
## 正文
|
||||
|
||||
### 和其他目录的边界
|
||||
|
||||
- 检查清单、模板、质量门禁和经验类内容优先收敛到本 README 的工程实践部分。
|
||||
- 技术选型、技术栈组合和学习路径优先收敛到本 README 的技术栈部分。
|
||||
- 新技术、工具趋势、优秀 repo 解析先放入 [research](../research/README.md)，形成稳定工程参考后再放入本目录。
|
||||
|
||||
## 维护规则
|
||||
### 维护规则
|
||||
|
||||
- 本目录采用“线性总文档”结构，正文统一收敛到 `README.md`。
|
||||
- 新增内容时优先追加到对应大章节，并同步补充总目录或细粒度目录。
|
||||
- 新增内容时优先追加到对应大章节，并同步补充快速导航或完整细粒度目录。
|
||||
- 不再新增同级主题 `.md` 文件；如确需拆分，必须同步更新全仓索引、AGENTS 与 metadata。
|
||||
- 目录内只保留 `README.md` 与 `AGENTS.md`。
|
||||
|
||||
|
||||
@@ -5,15 +5,16 @@
|
||||
|
||||
> `references/` 是工程实践、技术栈、模板、清单、质量门禁和可复用经验的线性手册。
|
||||
|
||||
## 核心摘要
|
||||
## 字多不看
|
||||
|
||||
> 生成规则：本文件由 `docs/references/sources/` 按文件名顺序拼接生成；请修改源片段后运行 `make sync-reference-readme`，不要直接编辑总文档主体。
|
||||
|
||||
- 本目录回答“具体工程怎么组织、怎么选技术、怎么设置硬门禁”。
|
||||
- 它承载稳定、可执行、可检查、可复用的工程参考资料。
|
||||
- 本 README 提供稳定锚点和细粒度目录，作为工程参考资料的统一入口。
|
||||
- 先看“工程实践”，获得项目架构、代码组织、开发经验、质量门禁和常见坑。
|
||||
- 再看“技术栈”，完成技术选型、组合案例判断和初学者学习路径设计。
|
||||
- 长文档优先走快速导航；需要完整索引时再展开细粒度目录。
|
||||
|
||||
## 常用入口
|
||||
## 快速导航
|
||||
|
||||
| 目标 | 直接跳转 |
|
||||
|:---|:---|
|
||||
@@ -26,26 +27,6 @@
|
||||
| 技术栈怎么选 | [如何选择技术栈](#tech-stack-selection) |
|
||||
| 初学者先学什么 | [初学者应该学什么技术栈](#reference-technology-stack-十五初学者应该学什么技术栈) |
|
||||
|
||||
## 总目录
|
||||
|
||||
1. [工程实践](#reference-engineering-practice) - 项目架构、代码组织、开发经验、质量门禁与常见坑。
|
||||
2. [技术栈](#reference-technology-stack) - 技术栈选型、组合案例与学习路径。
|
||||
|
||||
## 折叠块语法
|
||||
|
||||
长目录统一使用 `details + summary`，常用入口放在折叠块外，完整细粒度目录放在折叠块内。
|
||||
|
||||
```md
|
||||
<details>
|
||||
<summary><strong>完整细粒度目录（点击展开/收起）</strong></summary>
|
||||
|
||||
### 细粒度目录
|
||||
|
||||
- [章节](#stable-anchor)
|
||||
|
||||
</details>
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary><strong>完整细粒度目录（点击展开/收起）</strong></summary>
|
||||
|
||||
@@ -360,16 +341,25 @@
|
||||
|
||||
</details>
|
||||
|
||||
## 和其他目录的边界
|
||||
## 使用方式
|
||||
|
||||
- 先从 [工程实践](#reference-engineering-practice) 判断项目结构、代码组织、质量门禁和常见坑。
|
||||
- 再从 [技术栈](#reference-technology-stack) 判断技术选型、组合案例和学习路径。
|
||||
- 只查具体问题时，优先使用上方“快速导航”和细粒度目录。
|
||||
- 本 README 是生成文件；新增或调整正文时先改 `docs/references/sources/`。
|
||||
|
||||
## 正文
|
||||
|
||||
### 和其他目录的边界
|
||||
|
||||
- 检查清单、模板、质量门禁和经验类内容优先收敛到本 README 的工程实践部分。
|
||||
- 技术选型、技术栈组合和学习路径优先收敛到本 README 的技术栈部分。
|
||||
- 新技术、工具趋势、优秀 repo 解析先放入 [research](../research/README.md)，形成稳定工程参考后再放入本目录。
|
||||
|
||||
## 维护规则
|
||||
### 维护规则
|
||||
|
||||
- 本目录采用“线性总文档”结构，正文统一收敛到 `README.md`。
|
||||
- 新增内容时优先追加到对应大章节，并同步补充总目录或细粒度目录。
|
||||
- 新增内容时优先追加到对应大章节，并同步补充快速导航或完整细粒度目录。
|
||||
- 不再新增同级主题 `.md` 文件；如确需拆分，必须同步更新全仓索引、AGENTS 与 metadata。
|
||||
- 目录内只保留 `README.md` 与 `AGENTS.md`。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user