aigroup-workflow 2.1.1 → 2.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/rules/coding-style.md +21 -1
- package/package.json +1 -1
|
@@ -16,12 +16,26 @@
|
|
|
16
16
|
- 不构建当下不需要的功能
|
|
17
17
|
- 避免投机性通用化
|
|
18
18
|
- 先简单做出来，需要时再重构
|
|
19
|
+
- **长度压力**：能用 50 行写清楚的逻辑，不写 200 行；写完先压一遍再提交
|
|
20
|
+
- 不给"不可能发生的情况"加保险（如内部受控数据再做 null 校验）；边界处的校验另由 [entropy.md Golden Rule 2](entropy.md) 强制
|
|
19
21
|
|
|
20
22
|
### 防御编程
|
|
21
23
|
- 在系统边界（用户输入、外部 API、文件读取）做输入校验
|
|
22
24
|
- 用 schema 校验，快速失败并给出明确错误
|
|
23
25
|
- 不信任外部数据
|
|
24
26
|
|
|
27
|
+
## 动手前澄清
|
|
28
|
+
|
|
29
|
+
写代码之前的强制流程：
|
|
30
|
+
|
|
31
|
+
1. **显式声明假设** — 把"我假设 X / 我以为 Y"写出来，别藏在脑子里。前提一旦错，所有产出都白费
|
|
32
|
+
2. **不确定就停下，不要猜** — 命名歧义、需求模糊、行为未定义时，明确说出"哪里不清楚"，不要靠猜继续
|
|
33
|
+
3. **多解读时呈选项** — 任务有 2 种以上合理解读时，把候选方案列给用户选，不替用户做决定
|
|
34
|
+
4. **复杂方案先反问** — 方案过度设计时，先质疑能否简化；用户坚持复杂方案才执行
|
|
35
|
+
5. **不知道现有约定就先读** — 新模块陌生时先翻 3 个相似实现 + 对应 `docs/rules/<lang>/`，再动手
|
|
36
|
+
|
|
37
|
+
不做这一步的代价：返工、与现有模式冲突、引入与项目品味不符的代码。
|
|
38
|
+
|
|
25
39
|
## File Organization
|
|
26
40
|
|
|
27
41
|
**多个小文件 > 少个大文件**：
|
|
@@ -64,6 +78,9 @@
|
|
|
64
78
|
- **先读后写** — 先理解现有代码模式再动手
|
|
65
79
|
- **精准修改** — 只改需要改的部分
|
|
66
80
|
- **闭环优先** — 先跑通再优化，不过度设计
|
|
81
|
+
- **跟随现有风格** — 即便现有写法不是你认为的最优，也保持一致；风格统一比单点最优更重要
|
|
82
|
+
- **改动孤立才清理** — 只删除你的改动产生的孤立 import / 局部变量；不相关的死代码标注出来但不动手（重构走独立 PR）
|
|
83
|
+
- **不在功能 PR 里偷重构** — 修一个功能时顺手重构其他模块 = 评审噩梦 + 回归风险，禁止
|
|
67
84
|
|
|
68
85
|
## Code Quality Checklist
|
|
69
86
|
|
|
@@ -73,7 +90,10 @@
|
|
|
73
90
|
- [ ] 函数小（< 50 行）
|
|
74
91
|
- [ ] 文件聚焦（< 800 行）
|
|
75
92
|
- [ ] 无深嵌套（≤ 4 层）
|
|
76
|
-
- [ ]
|
|
93
|
+
- [ ] 错误处理完整，边界处有校验
|
|
77
94
|
- [ ] 无硬编码值（用常量或 config）
|
|
78
95
|
- [ ] 中文注释规范，无尾行注释
|
|
96
|
+
- [ ] 改动范围与任务直接相关；不相关代码已标记但未顺手改
|
|
97
|
+
- [ ] 风格与本模块/项目现有写法一致
|
|
98
|
+
- [ ] 没有为不可能发生的情况加保险逻辑
|
|
79
99
|
- [ ] 通过 `node scripts/hooks/dispatcher.cjs stop`
|