让你的Ai氛围编程更有效的进行

# AI文档规范体系

一、最高优先级原则

1. 必须阅读全部相关文档后，方可执行任何其他操作。任何未遵守此原则的操作无效并必须立即停止。
2. 所有规则中，本最高优先级原则优先于其他所有规则，其他规则不得与之冲突或削弱其效力。

二、文档生成及读取规范

3. 必须在项目根目录创建并维护文件：【文档生成及读取规范.md】（以下简称“规范”）。
4. 在执行任何与文档或代码相关的任务前，必须先阅读并理解【规范.md】的全部内容。
5. 【规范.md】必须至少包含以下章节与结构：
   5.1 文档命名规则（前缀/类型/日期/版本号/作者/关键词）
     5.2 文档路径与目录结构（项目文档文件夹的分类树与命名）
     5.3 必填元数据字段清单与格式（模板中不可省省的项）
     5.4 版本号规则与变更日志模板
     5.5 文档模板清单（类型、路径、用途、更新频率、负责人）
     5.6 文档读写流程与检查清单（必须步骤、强制阈值、审核点）
     5.7 质量标准与失效条件（清晰、完整、可追溯、可审计、与代码一致性等）
6. 任何文档的新增或更新，必须严格符合【规范.md】的要求，否则视为无效并需立即整改。

三、计划书与文档先行

7. 在修改代码前，必须先创建或更新对应的【计划书.md】。计划书未就绪前不得执行代码修改。
8. 【计划书.md】必须包含：
   8.1 目标与变更范围（明确“要改什么”“不改什么”）
     8.2 影响评估与依赖（对现有功能与文档的影响点与风险）
     8.3 实施步骤与检查点（步骤清单、验收条件）
     8.4 回滚方案与失败判定（如何撤销、何为失败）
     8.5 所需文档清单与模板引用（需同步创建/更新的文档及其路径）
     8.6 审批与共识要求（必须的确认人/角色与审批签名）

四、修改与文档联动

9. 每次代码修改必须同步更新或创建相关文档，确保代码与文档严格一致。
10. 【代码修改文档】命名规则：
      10.1 必须包含可溯源的代码实体名称（如模块/组件/类/函数/文件/目录名）
      10.2 必须包含修改动作类型（如新增/删除/重构/修正/优化）
      10.3 推荐结构：[代码实体名称]_[修改类型]_[日期]_[版本号].md
      10.4 禁止使用模糊、不可逆、不可读的名称
11. 【代码修改文档】内容至少包含：
      11.1 修改前后代码要点对比（必须标明修改了什么文件、具体第几行，且强制使用目录树表明修改文件的位置 [1]；包含函数名/接口签名的变更）
      11.2 变更原因与影响点（影响范围、接口兼容性、性能、安全等）
      11.3 测试与验证记录（用例、结果、截图/链接、结论）
      11.4 相关文档引用（哪些文档需同步更新，并提供链接）

五、文档组织与归档

12. 所有项目文档必须统一归档在【项目文档文件夹】内。
13. 【项目文档文件夹】目录结构：
      13.1 顶层划分（强制） [1]：
    - 01-规范/（制度、模板、检查清单） [1]
    - 02-计划/（计划书按时间/项目/模块索引） [1]
    - 03-设计/（架构、接口、流程、数据模型、时序图） [1]
    - 04-模块/（用于确定修改了什么模块及其变更记录） [1]
      13.2 二级及以下目录按【模块/组件/子系统/类型/时间】划分，必须使用数字前缀排序（如01-、02-），禁止使用模糊、不可读、不可溯源的名称 [1]。
      13.3 目录命名必须使用数字前缀排序，统一使用小写英文、连字符分隔，禁止混用中文与特殊字符 [1]。
14. 每份文档必须在【项目文档文件夹】内有唯一、可追溯的路径与引用。

六、强制整理与修复

15. 若项目不满足以上任一条款，必须优先执行整理与修复：
      15.1 立即停止新增代码，优先完成文档与计划书补齐。
      15.2 限期对【规范.md】与【计划书.md】进行落地与版本化。
      15.3 对已有代码补齐【代码修改文档】，确保可追溯与可审计。
      15.4 对不合规的目录与命名进行批量重命名与归档。
16. 整理完成前，不得提测、部署或合并主干。

七、强制检查与审计

17. 所有文档与代码变更必须经过检查清单审计，清单至少包含：
      17.1 已阅读并理解【规范.md】全部内容。
      17.2 已创建或更新【计划书.md】并完成审批。
      17.3 已创建或更新【代码修改文档】并包含必要章节。
      17.4 已归档至【项目文档文件夹】指定目录并完成版本标记。
      17.5 代码与文档一致性校验通过（无过时、无矛盾、无遗漏）。
18. 未通过审计的变更不得继续，必须立即整改并重新审计。

八、用语与执行

19. 本规范使用强制术语：必须/禁止/不得/除非/否则/立即/强制/停止/优先/校验/审计/归档。
20. 遇到冲突时，以【最高优先级原则】为准，确保全文无歧义、无例外、不减弱。

生效范围：所有由本系统生成的项目、文档与代码变更。未明确列为可选的项目均为强制执行。

# 文档目录树规范（强制执行版）

一、顶层目录结构（强制）

1. 项目根目录
   ├─ 【项目文档文件夹】/（全部项目文档统一归档）
   └─ 【文档生成及读取规范】.md（必须置于根目录）

2. 【项目文档文件夹】顶层结构（强制）：
   ├─ 01-规范/（制度、模板、检查清单）
   ├─ 02-计划/（计划书按时间/项目/模块索引）
   ├─ 03-设计/（架构、接口、流程、数据模型、时序图）
   └─ 04-模块/（用于确定修改了什么模块及其变更记录）

二、二级目录结构（强制）

1. 01-规范/
   ├─ 01-文档规范/
   │  ├─ [文档生成及读取规范]_模板.md
   │  ├─ [命名规则]_最新版.md
   │  └─ [格式标准]_检查清单.md
   ├─ 02-代码规范/
   │  ├─ [编码规范]_最新版.md
   │  ├─ [命名规则]_代码实体.md
   │  └─ [注释规范]_检查清单.md
   ├─ 03-流程规范/
   │  ├─ [开发流程]_标准版.md
   │  ├─ [变更流程]_审批链.md
   │  └─ [发布流程]_验收标准.md
   └─ 04-模板库/
      ├─ [计划书模板].md
      ├─ [代码修改文档模板].md
      └─ [其他模板]_按需添加.md

2. 02-计划/
   ├─ 01-按年度/
   │  ├─ 2026/
   │  │  ├─ 01-一月/
   │  │  │  ├─ [项目_模块]_[计划]_20260115_v1.0.md
   │  │  │  └─ [项目_模块]_[计划]_20260120_v1.2.md
   │  │  ├─ 02-二月/
   │  │  └─ ...
   ├─ 02-按项目/
   │  ├─ [项目名称_A]/
   │  │  ├─ [模块A1]_[计划]_[日期]_[版本].md
   │  │  └─ [模块A2]_[计划]_[日期]_[版本].md
   │  └─ [项目名称_B]/
   └─ 03-索引/
      ├─ [计划总览]_按时间.md
      └─ [计划总览]_按项目.md

3. 03-设计/
   ├─ 01-架构设计/
   │  ├─ [系统架构]_总览_[日期]_[版本].md
   │  ├─ [技术栈]_选型_[日期]_[版本].md
   │  └─ [分层架构]_定义_[日期]_[版本].md
   ├─ 02-接口设计/
   │  ├─ [API模块_A]_接口定义_[日期]_[版本].md
   │  ├─ [API模块_B]_接口定义_[日期]_[版本].md
   │  └─ [接口契约]_校验_[日期]_[版本].md
   ├─ 03-数据模型/
   │  ├─ [数据库]_表结构_[日期]_[版本].md
   │  ├─ [对象模型]_定义_[日期]_[版本].md
   │  └─ [ER图]_关系_[日期]_[版本].md
   ├─ 04-流程设计/
   │  ├─ [业务流程_A]_时序_[日期]_[版本].md
   │  └─ [业务流程_B]_时序_[日期]_[版本].md
   └─ 05-图表资源/
      ├─ [架构图]_绘制工具版本
      └─ [流程图]_绘制工具版本

4. 04-模块/
   ├─ [模块名称_A]/
   │  ├─ [实体名称_A1]_[修改类型]_[日期]_[版本].md
   │  └─ [实体名称_A2]_[修改类型]_[日期]_[版本].md
   ├─ [模块名称_B]/
   │  └─ [实体名称_B1]_[修改类型]_[日期]_[版本].md
   └─ 01-变更日志/
      └─ [变更日志]_汇总_[日期]_[版本].md

三、命名规则（强制）

1. 目录命名规则：
   1.1 必须使用数字前缀排序：01-、02-、03-、04-
   1.2 必须使用小写英文、连字符分隔，禁止混用中文与特殊字符
   1.3 二级及以下目录按【模块/组件/子系统/类型/时间】划分
   1.4 禁止使用模糊、不可读、不可溯源的名称

2. 文件命名规则：
   2.1 必须包含可溯源的代码实体名称（如模块/组件/类/函数/文件名）
   2.2 必须包含文档类型或修改动作类型（如计划/修改/新增/重构）
   2.3 必须包含日期（格式：YYYYMMDD）
   2.4 必须包含版本号（格式：vX.Y，X为主版本号，Y为次版本号）
   2.5 推荐结构：[实体名称]_[文档类型]_[日期]_[版本].md
   2.6 禁止使用空格、特殊字符、中文标点

四、版本管理（强制）

1. 文档版本号规则：
   1.1 主版本号（X）：重大变更、不兼容修改
   1.2 次版本号（Y）：功能新增、兼容性修改
   1.3 修订号（Z）：Bug修复、文档修正（如需）
   1.4 版本号必须连续，不得跳跃

2. 变更日志要求：
   2.1 每次文档更新必须更新变更日志章节
   2.2 变更日志必须包含：版本号、日期、作者、变更内容
   2.3 必须说明变更原因和影响范围

五、归档与清理（强制）

1. 归档规则：
   1.1 已完成的项目必须归档至【项目文档文件夹】内的归档目录
   1.2 归档目录结构：01-规范/归档/、02-计划/归档/、03-设计/归档/、04-模块/归档/
   1.3 归档文档必须保持原始目录结构和命名规则
   1.4 归档文档必须添加归档标记（日期、归档人、归档原因）

2. 清理规则：
   2.1 过期文档必须移至归档目录，不得直接删除
   2.2 重复文档必须合并，保留最新版本
   2.3 无效文档必须标记为【已作废】，保留90天后方可删除
   2.4 清理操作必须记录在【清理日志】中，包含：日期、操作人、清理原因

六、强制检查清单（执行前必读）

1. 目录结构检查：
   □ 是否存在【项目文档文件夹】
   □ 是否存在【文档生成及读取规范】.md
   □ 是否存在01-规范至04-模块四个顶层目录
   □ 目录命名是否符合数字前缀+小写英文+连字符规则
   □ 文档是否归档至正确的二级/三级目录

2. 文件命名检查：
   □ 文件名是否包含可溯源的实体名称
   □ 文件名是否包含文档类型或修改动作类型
   □ 文件名是否包含日期（YYYYMMDD格式）
   □ 文件名是否包含版本号（vX.Y格式）
   □ 文件名是否使用连字符分隔，无特殊字符

3. 版本管理检查：
   □ 文档版本号是否连续，无跳跃
   □ 变更日志是否完整，包含必要字段
   □ 归档文档是否保留原始结构和命名规则
   □ 归档文档是否添加归档标记

七、执行与审计（强制）

1. 所有文档创建、更新、归档、清理操作必须经过强制检查清单审计
2. 未通过审计的文档操作不得继续，必须立即整改并重新审计
3. 审计记录必须保存在【审计日志】中，包含：日期、操作人、审计结果、整改措施

生效范围：所有由本系统生成的项目文档目录结构与命名规则。未明确列为可选的项目均为强制执行。

# 【强制阅读规则（最高优先级）】

一、绝对强制原则

1. 在执行任何代码相关操作前，必须先完整阅读所有相关文档。
2. 未完成文档阅读前，禁止进行任何代码生成、修改或建议。
3. 阅读完整性要求：不得遗漏任何文件，不得跳过任何章节，不得忽略任何依赖关系。

二、文档阅读强制流程（必须按顺序执行）

1. 第一步：文件识别
   - 必须列出所有提供的文档文件清单
   - 必须按优先级排序文档（规范→设计→实现→测试）
   - 必须标记文档类型（规范/设计/代码/配置/文档）

2. 第二步：逐文件深度分析
   对每个文件必须执行：
   - 理解文件的主要功能和目的（禁止模糊理解）
   - 识别所有类、函数、接口（禁止遗漏关键定义）
   - 记录文件之间的依赖关系（必须构建依赖图谱）
   - 提取关键配置信息、常量定义（必须记录上下文）
   - 识别潜在风险点和技术债务（必须标注）
   - 记录未明确说明的隐含约束（必须推断）

3. 第三步：跨文件关联分析
   必须执行以下分析：
   - 构建完整的项目架构图（模块、组件、层次关系）
   - 识别关键依赖路径（单向依赖/双向依赖/循环依赖）
   - 识别数据流向（输入→处理→输出）
   - 识别关键接口和契约（API、协议、数据格式）
   - 识别潜在冲突点（命名冲突、逻辑冲突、资源竞争）

三、强制输出机制（阅读完成前不得跳过）

1. 必须输出"文档阅读清单"（格式如下）：

   【文档阅读清单】
   ├─ 已读取文件列表：[完整文件名清单]
   │  ├─ [文件1] - [类型] - [优先级] - [状态：已理解/需确认]
   │  ├─ [文件2] - [类型] - [优先级] - [状态：已理解/需确认]
   │  └─ ...
   ├─ 文件结构概要：[完整架构描述]
   │  ├─ 顶层架构：[模块划分与职责]
   │  ├─ 关键组件：[核心类/函数/接口清单]
   │  └─ 技术栈：[语言/框架/工具/版本]
   ├─ 关键依赖关系：[依赖关系图]
   │  ├─ 模块依赖：[依赖关系描述]
   │  ├─ 数据流向：[数据流转路径]
   │  └─ 接口契约：[API/协议清单]
   └─ 风险点识别：[潜在问题与冲突点]
      ├─ 架构风险：[设计缺陷/不合理耦合]
      ├─ 逻辑风险：[潜在bug/边界条件]
      └─ 实现风险：[性能/安全/可维护性问题]

2. 必须确认理解程度：

   - 对每个文件标记理解状态：完全理解/基本理解/需要澄清
   - 对不确定的部分必须明确标注为【待确认项】
   - 对缺失的文档必须明确标注为【文档缺失项】

3. 必须回答确认问题：

   - 是否已完整阅读所有文档？（必须回答：是/否）
   - 是否理解项目整体架构？（必须回答：是/否/部分）
   - 是否识别出所有关键依赖？（必须回答：是/否/不确定）
   - 是否发现潜在冲突或风险？（必须回答：是/否/不确定）

四、强制确认机制（未确认前禁止编码）

1. 必须回复以下确认语句（禁止省略或修改）：
   "【确认声明】已完整阅读所有文档，确认理解项目架构，已识别关键依赖关系，未发现阻塞性问题，准备开始编码。"

2. 如发现文档缺失或不完整，必须回复：
   "【警告声明】文档不完整，缺失以下关键信息：[列出缺失项]，建议补充后继续。"

3. 如发现架构冲突或不一致，必须回复：
   "【风险声明】发现以下潜在冲突：[列出冲突点]，建议解决后继续。"

五、强制检查清单（阅读完成前必须逐项确认）
□ 已列出所有文档文件清单
□ 已识别所有文件类型和优先级
□ 已理解每个文件的主要功能和目的
□ 已识别所有类、函数、接口定义
□ 已记录所有文件间依赖关系
□ 已提取所有关键配置和常量
□ 已构建完整架构图
□ 已识别数据流向和关键接口
□ 已标注所有潜在风险点
□ 已输出完整文档阅读清单
□ 已完成确认声明

六、违反规则处理（强制执行）

1. 未完成文档阅读即进行编码的操作视为无效。
2. 阅读清单不完整的输出视为无效。
3. 确认声明缺失的操作视为无效。
4. 发现文档问题未声明的情况视为违规。
5. 所有违规操作必须立即停止，重新执行完整阅读流程。

生效范围：所有涉及代码生成的任务，包括但不限于：新功能开发、Bug修复、代码重构、性能优化、安全加固等。

# 代码修改规则

一、最小化修改原则（强制执行）  

1. 必须仅修改与需求/缺陷直接相关的代码部分，禁止进行无关变更。  
2. 修改前必须执行影响范围评估，识别所有可能受影响的现有功能。  
3. 必须优先采用局部修改方案，禁止未经审批的大范围重构。  
4. 必须保持修改的原子性，禁止在单次修改中耦合多个变更。  
5. 单次修改必须完成单一目标，禁止混合多个无关目标。  

二、复用优先原则（强制执行）  

1. 必须优先复用现有代码，禁止重复造轮子。  
2. 修改前必须查找现有工具类/组件库，优先使用已有实现。  
3. 继承优于复制，组合优于继承，必须遵循设计复用原则。  
4. 必须参考类似功能的实现方式，保持代码一致性。  

三、代码即文档原则（强制执行）  

1. 必须严格贯彻“代码即文档”理念，确保代码结构和命名能够直观反映业务逻辑，保证代码本身一看就知道是干什么的。  
2. 变量、函数、类的命名必须完全自描述，做到“见名知意”，禁止过度依赖外部注释来弥补糟糕的命名。  
3. 注释必须与代码逻辑高度一致，禁止存在过时、误导或纯粹重复代码的废注释，保证注释一看就知道对应代码的目的。  
4. 复杂的控制流必须通过合理抽取函数、使用卫语句等手段降低嵌套，使代码本身成为业务流程的最佳说明书。  
5. 任何代码修改必须同步更新关联注释，保证代码与文档的绝对一致性，禁止出现“文不对码”的现象。  

四、注释规范（强制执行）  

1. 代码生成时必须写入注释，禁止无注释的关键代码。  
2. 注释必须简洁明了，明确标明代码用途和功能。  
3. 复杂逻辑必须添加实现思路说明，禁止含糊不清的注释。  
4. 修改历史必须标注修改原因和日期，禁止无记录的代码变更。  
5. 接口方法必须添加参数说明和返回值说明，禁止缺少文档注释。  
6. 临时方案必须标注TODO和后续改进计划，禁止无期限的临时代码。  

五、代码风格（强制执行）  

1. 必须严格遵循项目现有代码风格规范，禁止风格不统一。  
2. 必须统一缩进、空格和换行格式，禁止格式混乱。  
3. 变量和函数命名必须体现业务语义，禁止无意义命名。  
4. 禁止过长的代码行，必须控制在合理长度内。  
5. 必须合理使用空行区分逻辑块，禁止逻辑混乱的代码结构。  

六、强制检查清单（执行前必读）  

1. 修改范围检查：  
   □ 是否仅修改需求/缺陷直接相关代码  
   □ 是否已完成影响范围评估  
   □ 是否采用局部修改方案  
   □ 是否保持修改原子性  

2. 复用性检查：  
   □ 是否查找并复用现有工具类/组件库  
   □ 是否遵循继承和组合原则  
   □ 是否参考类似功能实现  

3. 代码即文档检查：  
   □ 代码命名是否达到“见名知意”且一看即懂  
   □ 代码逻辑是否足够清晰以充当业务流程说明  
   □ 注释是否与代码完全同步且无歧义  
   □ 是否存在过度依赖注释掩盖糟糕代码结构的情况  

4. 注释检查：  
   □ 是否添加用途说明注释  
   □ 复杂逻辑是否添加实现思路说明  
   □ 是否标注修改历史（原因和日期）  
   □ 接口方法是否添加参数和返回值说明  
   □ 临时方案是否标注TODO和改进计划  

5. 代码风格检查：  
   □ 是否遵循项目代码风格规范  
   □ 是否统一缩进、空格和换行格式  
   □ 命名是否体现业务语义  
   □ 代码行长度是否合理  
   □ 是否合理使用空行区分逻辑块  

七、强制执行与审计（强制执行）  

1. 所有代码修改必须经过强制检查清单审计。  
2. 未通过审计的代码修改不得提交，必须立即整改并重新审计。  
3. 审计记录必须保存在【代码修改日志】中，包含：日期、修改人、审计结果、整改措施。  

生效范围：所有由本系统生成的代码修改。未明确列为可选的项目均为强制执行。