qzero-code-style

name	qzero-code-style
description	写代码和做 Git 提交时必须遵循本仓库中的规范文档，并持续积累经验。

我的编码风格

代码规范

在编写任何代码之前，必须先完成以下两项准备工作：

1. 读取 CODE_STYLE.md，对照其中的每一条规则检查即将编写的代码。
2. 按时间从近到远的顺序，查看 ~/.code_style/ 目录下至少 5 份经验总结文档（如果不足 5 份则全部查看），回顾以往犯过的错误，避免重复踩坑。

借鉴经验总结的规则：

• 经验总结的优先级低于 CODE_STYLE.md 和 GIT_STYLE.md 中的正式规范。如果经验文档中的内容与正式规范有冲突，以正式规范为准。
• 一个仓库只能借鉴来自于它自身的经验，禁止跨仓库借鉴经验总结（除非用户明确提出需要跨仓库借鉴的需求）。这里的"仓库"指的是 git 仓库所在的目录，即 git rev-parse --show-toplevel 返回的路径。判断一条经验是否属于当前仓库，依据是经验文档中记录的"代码库路径"是否与当前仓库路径一致。

编写完成后，再次对照 CODE_STYLE.md 逐条自查，确保没有违反任何规则。

Git 提交规范

在进行任何 Git 提交之前，必须先阅读并遵循本仓库中的 GIT_STYLE.md 文件。

具体要求：

1. 每次 git commit 之前，先读取 GIT_STYLE.md，确保 commit message 格式正确。
2. 提交信息第一行使用 <type>(<scope>): <description> 格式，description 部分用中文。
3. 提交信息主体中必须说明：修改的主要内容及要解决的问题，以及每个文件的修改内容与原因。

经验积累

每次 git commit 成功之后（或者用户明确要求"积累这次的经验"时），按以下原则判断是否需要执行经验积累流程：

1. 有值得总结的经验才总结：如果本轮对话中没有出现需要纠正的代码风格问题，则无需强行总结。经验积累的目的是从错误中学习，不是为每一笔提交写日志。
2. 仅针对代码：经验总结的范围限定在代码层面。除非用户明确要求，否则代码以外的场景（如文档排版、目录结构、配置调整等）不需要纳入经验总结。
3. 一遍过的代码无需总结：如果你生成的代码未经用户指正或修改就直接提交了，说明这部分代码没有暴露风格差距，无需积累经验。

如果判定需要总结，则执行以下流程：

第一步：总结差距

仔细回顾本次对话的完整过程，对比以下两个版本之间的差异：

• 你最初实现的版本（bad case）：未经用户纠正的原始代码
• 用户指导修改后的最终版本（good case）：经过用户多轮反馈后最终的代码
• 如果用户在对话过程中手动修改了代码，这些手动修改尤为重要，必须重点分析

重点总结：用户预期的代码风格与你实际写出的代码风格之间的差距，以及用户纠正你的模式是什么。总结中必须附上实际的代码片段作为 bad case 和 good case 的对比。

第二步：向用户确认

将总结的经验教训展示给用户，明确地请用户确认以下三点：

1. 经验总结是否准确反映了用户的意图？
2. bad case 和 good case 的代码是否真实反映了差距？
3. 是否有遗漏或需要补充的内容？

必须在用户认可之后，才能进入第三步。

第三步：写入经验文档

在 ~/.code_style/{YYYY-MM-DD}.md 中以追加写的形式记录本次经验。每份文档必须包含：

# 经验总结 - YYYY-MM-DD

## 元信息
- 代码库路径：<git 仓库根目录的绝对路径（即 `git rev-parse --show-toplevel` 的输出）>
- Commit Hash：<本次提交的完整 hash>
- 分支：<分支名>

## 经验教训

### 经验 1：<简短标题>

**触发场景**：<什么情况下会犯这个错误>

**Bad Case**
```语言
// 最开始写的代码
```

**Good Case**
```语言
// 用户指导下修改后的代码
```

**教训**：<从这次差距中总结出的规律>

如果有多次经验（多个被纠正的点），则在"经验教训"下依次记录为"经验 2""经验 3"等。

经验沉淀到编码规范

如果用户要求将经验文档中的某条 case 沉淀到 CODE_STYLE.md 中，则需要：

1. 将那条经验的代码进行脱敏处理：模糊化具体的业务场景名称、类名、路径等，替换为通用的示例命名。
2. 将脱敏后的规则以新增条目的形式写入 CODE_STYLE.md（编号顺延）。
3. 沉淀完成后向用户报告新增的条目编号和内容摘要。

这一流程确保了经验不会只停留在历史文档中，而是会逐步固化为正式的编码规范。