Accueil Explorer Aide
S'inscrire Connexion
haiany
/
QMAI
miroir de https://github.com/Mochocyang/QMAI.git
1
0
Fork 0
Fichiers Tickets 0 Wiki
Aborescence: 0d3c2dfddf
Branches Tags
QMAI
/
CLAUDE.md

CLAUDE.md 10 KB
Historique Raw

开发协作准则

目标

本准则用于约束项目内所有代码修改、功能增加、调试、测试、打包与上传相关工作，确保每一次变更都做到：

  1. 目标明确。
  2. 改动可控。
  3. 功能不回退。
  4. 结果可验证。
  5. 交付可追踪。
  6. 文件上传范围准确。

一、总原则

  1. 先思考，再写代码。
  2. 不要想当然，不要掩盖困惑。
  3. 只写解决问题所需的最少代码。
  4. 只改必须改的地方。
  5. 不顺手重构无关代码。
  6. 不删除已有函数，除非用户明确要求。
  7. 每一行改动都必须能直接追溯到用户需求。
  8. 不确定时先说明假设和权衡，必要时先提问。
  9. 新功能和修改都要优先保证现有功能不回退。
  10. 所有面向用户的提示语、弹窗、确认信息、风险说明、操作说明，必须使用中文。
  11. 每一步都要分析，这次修改会不会影响其他功能设计？如果会影响其他功能，让其他功能丢失，那便询问用户，由用户确认，如果不会影响其他功能，那就继续开始处理
  12. 每一次修改新增功能都必须要有计划，必须落实计划。打包除外！其他都必须要有计划。

二、开始实现前的要求

在开始任何代码修改、功能增加、调试或打包前，必须先完成以下事项：

  1. 明确本次任务目标。
  2. 明确成功标准。
  3. 明确本次准备修改哪些文件。
  4. 检查项目当前结构、相关文件和现有实现风格。
  5. 固定当前能正常工作的版本。
  6. 如果是新增功能，必须放到独立功能分支中处理。
  7. 如果存在多种实现方式，先说明不同方案、取舍和推荐方案。
  8. 如果需求存在歧义，必须先提问，不要自行脑补。

三、代码修改原则

代码修改必须遵守以下原则：

  1. 不添加用户没有要求的功能。
  2. 不为一次性场景做过度抽象。
  3. 不加入未被要求的灵活性或配置项。
  4. 不为实际上不会发生的场景编写多余处理。
  5. 不顺手修改无关代码、注释或格式。
  6. 不重构没有坏掉的部分。
  7. 保持与现有代码风格一致。
  8. 修改后及时清理自己引入的无用 import、变量、函数和临时代码。
  9. 不删除原本就存在的死代码，除非用户明确要求。
  10. 每一行改动都应当能说明它为什么服务于当前需求。

四、功能增加流程

增加功能时必须严格按照以下流程执行，防止新增功能导致旧功能丢失或回退：

  1. 先把当前能正常工作的版本固定下来。
  2. 新功能必须放到独立功能分支中开发。
  3. 每个功能分支只做一个新功能。
  4. 创建分支的名称用中文拼音不用英文-比如模型设置分支，名称为moxingshezhi ，比如拆书库。名称为chaishuku ，每个分支下都需要创建一个说明md文档，这个分支下详细说明这个分支的使用要求，每次更新的内容也都要添加在分支当中，是否提交也需要填写在分支文档中。
  5. 分支必须保持稳定、可打包。
  6. 修改前先说明准备改哪些文件。
  7. 只实现当前功能所需的最小改动。
  8. 不重构无关代码。
  9. 不删除已有函数。
  10. 新功能完成后，先运行源码。
  11. 再跑旧功能测试，确认旧功能没有回退。
  12. 确认没问题后再打包。
  13. 每次修改完或增加完功能都要打包。
  14. 打包成功后，再考虑合并回master 分支。
  15. 新功能完成后，列出所有改动点。

五、测试与验证要求

任务必须以可验证目标为导向推进。

1. 常规验证

修改完成后，应按顺序执行：

  1. 运行源码或基础启动流程。
  2. 运行旧功能测试。
  3. 运行当前功能相关测试。
  4. 运行 lint、typecheck、build 或项目已有的验证命令。
  5. 确认没有新增错误、警告或回退问题。

2. Bug 修复验证

修复 bug 时应优先：

  1. 先明确问题表现。
  2. 尽量写出能复现问题的测试或复现步骤。
  3. 再进行修复。
  4. 修复后确认问题不再出现。
  5. 同时确认旧功能没有被破坏。

3. 重构验证

重构时必须确认：

  1. 改动前后行为一致。
  2. 原有测试通过。
  3. 没有新增功能差异。
  4. 没有扩大修改范围。

六、打包要求

  1. 每次修改完或增加完功能，都必须打包，比如当前软件版本是2.2.9那么下次打包也是2.2.9。打包之后在"E:\QMAI\GenxinLOG\更新日志.md"当中列出更新内容。
    1. 日志要求：
      1. 更新日志当中加入时间，比如20260609-时间，下面显示更新内容。
      2. 当用户要求提交github之后，软件版本号则自动更新+1,另外在E:\QMAI\GenxinLOG目录下重新创建一个新的更新日志md文档，名称格式：20260609-时间-更新日志。在没有提交github时一直沿用这个更新日志，当github提交之后则重新开一个新的日志MD文档。
  2. 打包前必须先确认源码运行正常。
  3. 打包前必须先确认旧功能没有回退。
  4. 打包应优先使用项目已有命令。
  5. 打包时尽量采用局部、低风险方式。
  6. 不要随意修改全局环境。
  7. 如果需要修改本地设置、执行命令或调整软件环境，必须先评估影响。
  8. 如果打包失败，必须说明失败原因、已验证内容和下一步处理建议。
  9. 打包上传github时，需要生成mac apple和intel版本 linux windows版本，上传命名规则，QMaiWrite_版本号_系统版本 比如 QMaiWrite_2.2.8_windows_X64.exe 更新日志只显示前5条，用户点击更多可查看全部更新。.
  10. 上传时必须要有latest.json，防止上传之后点击检查更新无法使用

七、本地环境与安全规则

  1. 严禁未经用户同意删除电脑文件。
  2. 禁止执行可能造成数据丢失的操作，包括删除、覆盖、批量移动、清空、卸载、重置等。
  3. 修改本地设置、执行命令、安装依赖或调整环境前，必须先评估影响。
  4. 优先选择局部、低风险方案。
  5. 不泄露、不记录、不提交任何密钥、令牌、密码或敏感信息。
  6. 不擅自提交 git，除非用户明确要求。
  7. 不擅自合并分支，除非用户明确要求。

八、上传前文件筛选要求

如果需要上传项目文件，必须先全面检查并筛选项目内容，只上传与软件直接相关的必要文件。

1. 允许上传的内容

只允许包含以下类型文件：

  1. 源代码文件，例如：

    • .java
    • .py
    • .js
    • .ts
    • .tsx
    • .rs
    • .css
    • .html

  2. 编译或构建配置文件，例如：

    • pom.xml
    • package.json
    • package-lock.json
    • Cargo.toml
    • Cargo.lock
    • tsconfig.json
    • vite.config.*
    • tauri.conf.json

  3. 软件运行或界面展示必须依赖的资源文件，例如：

    • 图标
    • 样式表
    • 字体
    • 必要图片
    • 必要配置资源

  4. 软件功能实现直接依赖的配置文件。

2. 必须排除的内容

上传时必须排除以下内容：

  1. 各类文档，例如：

    • README.md
    • 技术文档
    • 用户手册
    • 说明文档
    • 临时整理文档

  2. 临时文件备份文件，例如：

    • IDE 缓存
    • 系统缓存
    • 临时外部下载文件
    • 临时脚本
    • .zip
    • QMdelete/ 、 reasonix.toml 、 tr master

  3. 编译中间产物，例如：

    • dist
    • build
    • target
    • .next
    • .vite

  4. 测试数据，例如：

    • 测试用例数据
    • 模拟数据
    • 临时样本数据

  5. 日志文件，例如：

    • .log
    • 运行日志
    • 调试日志

  6. 版本控制相关内容，例如：

    • .git 目录
    • Git 内部对象
    • 无关历史文件

  7. 其他与软件功能实现无直接关联的内容。

  8. 禁止上传GenxinLOG文件夹下的所有内容

  9. 禁止上传tests文件夹下所有内容

3. 上传前清单

上传前必须完成以下检查：

  1. 全面检查项目文件。
  2. 剔除不相关内容。
  3. 确认只保留必要文件。
  4. 确认没有密钥、令牌、密码或隐私信息。
  5. 输出最终文件列表清单供用户确认。
  6. 用户确认后再执行上传。上传命名规则，QMaiWrite_版本号_系统版本 比如 QMaiWrite_2.2.8_windows_X64.exe 更新日志只显示前5条，用户点击更多可查看全部更新。.

九、Git 使用要求

  1. main 分支必须保持稳定、可打包。
  2. feature 分支每次只增加一个新功能。
  3. 新功能应在独立分支中完成。
  4. 不要在未确认旧功能正常前合并分支。
  5. 不要未经用户明确要求执行 git commit。
  6. 不要未经用户明确要求执行 git merge。
  7. 修改完成后，应说明当前是否已提交 git。
  8. 如果未提交，应明确说明“未提交”。

十、任务汇报要求

任务完成后，必须尽量向用户反馈以下内容：

  1. 是否完成。
  2. 本次改动了哪些内容。
  3. 修改了哪些文件。
  4. 是否运行了源码。
  5. 是否运行了旧功能测试。
  6. 是否执行了 lint、typecheck、build 或其他验证命令。
  7. 是否完成打包。
  8. 是否存在风险或限制。
  9. 是否已 git 提交。
  10. 下一步建议是什么。
  11. 如果任务完整结束，说明是否还有继续优化的内容。

十一、协作方式

  1. 需求不清时先澄清，不要自行脑补。
  2. 遇到多种可能方案时，先列出选项并说明取舍。
  3. 任务较复杂时，先给出简短计划，再逐步推进。
  4. 修改必须尽量外科手术式，避免波及无关模块。
  5. 如果发现无关问题，可以提醒用户，但不要擅自修改。
  6. 如果发现当前方案过于复杂，应主动提出更简单方案。
  7. 如果用户要求的方案存在风险，应明确指出并给出替代方案。

十二、成功标准

一个任务只有同时满足以下条件，才可以认为完成：

  1. 用户要求的目标已经实现。
  2. 没有添加用户未要求的功能。
  3. 没有删除用户未要求删除的内容。
  4. 没有破坏旧功能。
  5. 已完成必要测试验证。
  6. 修改后已完成打包。
  7. 已说明风险和限制。
  8. 已说明是否提交 git。
  9. 已给出下一步建议。