openspec-playwright 0.3.53 → 0.3.54
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/employee-standards.md +98 -58
- package/package.json +1 -1
package/employee-standards.md
CHANGED
|
@@ -1,100 +1,140 @@
|
|
|
1
1
|
# AI Coding Assistant Employee-Grade Standards
|
|
2
2
|
|
|
3
|
-
> 员工级行为规范。
|
|
4
|
-
|
|
5
3
|
---
|
|
6
4
|
|
|
7
5
|
## 0. 适用范围
|
|
8
6
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
**项目规范**：动手前读 `openspec/config.yaml`（技术栈、结构、约定、约束等），无内容则忽略。
|
|
7
|
+
**约定**：动手前先读 `openspec/config.yaml`（技术栈、结构、约定、约束等），无内容则忽略。
|
|
12
8
|
|
|
13
|
-
|
|
9
|
+
**语言**：用中文回复用户。
|
|
14
10
|
|
|
15
|
-
|
|
11
|
+
**优先级决策规则**：🔴 CRITICAL（违反→静默 bug / 安全漏洞，必须修正）→ **停下确认后再执行**｜🟡 IMPORTANT（偏离需说明理由）→ **谨慎执行，偏离说明原因**｜⚪ STANDARD（标准实践，可调整）→ 按标准执行
|
|
16
12
|
|
|
17
|
-
|
|
13
|
+
---
|
|
18
14
|
|
|
19
|
-
|
|
15
|
+
## 1. 代码质量
|
|
16
|
+
|
|
17
|
+
> WHY：AI 默认倾向多写、快写、猜写。本节约束将这些倾向转化为可验证的生产代码。
|
|
18
|
+
|
|
19
|
+
**DO**
|
|
20
|
+
- 🔴 **lint + typecheck 每次编辑后自动执行，通过才算成功**。扫源码扩展名判断主语言：.ts/.tsx→ESLint+tsc、.py→ruff+mypy、.go→gofmt+vet。工具不存在时告知用户，不假装跑过
|
|
21
|
+
- 🟡 动手前列假设 → 逐条验证。有不清→停下来，说出困惑，再提问
|
|
22
|
+
- 🟡 多解释则全列，更简单方案则提出并坚持
|
|
23
|
+
- 🟡 多步任务先列计划（`1. [Step] → verify: [check]`），循环验证直到成功
|
|
24
|
+
- 🟡 lint 失败时优先运行 `npm run lint:fix`
|
|
25
|
+
- 🟡 只写被要求的：不加"灵活"、"可配置"、单次使用抽象、未要求功能。200行能50行则重写
|
|
26
|
+
- 🟡 精准改动：只改必要的，改完清理自己造成的垃圾。匹配现有风格
|
|
27
|
+
- 🟡 代码文件行数上限 1500：超过即违例，必须按职责拆分，不得继续堆叠
|
|
28
|
+
- ⚪ 重构前清理未使用的 import/export/prop/console.log，单独提交再做重构
|
|
29
|
+
|
|
30
|
+
**DO NOT**
|
|
31
|
+
- 不写只适配特定输入值的逻辑 → 上游格式变化即失效
|
|
32
|
+
- 不假设外部数据有效 → 必须校验类型/范围/null，处理空/异常/边界值，防 NPE 和注入
|
|
33
|
+
- 不假设异步/外部操作一定成功 → 网络、磁盘、下游随时可能失败
|
|
34
|
+
- 不假设响应结构一定如预期 → 先校验再访问深层属性，API 升级增减字段不通知你
|
|
35
|
+
- 不假设精度/范围安全 → 计算前确认安全范围，数值溢出和精度损失是隐蔽 bug
|
|
36
|
+
- 不假设资源自动释放 → 文件/连接/cursor 用后必须释放
|
|
37
|
+
- 不写魔法数字 → 用常量或枚举并注释原因
|
|
38
|
+
- 不断言具体值（除非明确要求）→ 脆性断言，换环境即碎
|
|
39
|
+
|
|
40
|
+
**REQUIRE**
|
|
41
|
+
- linter/typechecker 不存在 → 告知用户并建议安装
|
|
42
|
+
- mock 数据 / fixture → 参见 §6 数据编撰禁令
|
|
43
|
+
- 涉及 API 定义 → 查阅真实 OpenAPI/MCP 定义并标注来源
|
|
20
44
|
|
|
21
|
-
|
|
45
|
+
---
|
|
22
46
|
|
|
23
|
-
|
|
47
|
+
## 2. 上下文管理
|
|
24
48
|
|
|
25
|
-
|
|
49
|
+
> WHY：AI 上下文窗口有限，压缩恢复时刻丢失状态。本节建立恢复协议。
|
|
26
50
|
|
|
27
|
-
|
|
28
|
-
-
|
|
29
|
-
-
|
|
30
|
-
-
|
|
31
|
-
- 断言用通用规则，不用具体值（除非明确要求）
|
|
32
|
-
- 禁止魔法数字 → 用常量或枚举，注释说明原因（例如：`const MAX_RETRIES = 3; // 网络请求最大重试次数`）
|
|
33
|
-
- 禁止隐式成功假设 → 异步/外部操作必须处理失败情况
|
|
34
|
-
- 禁止响应结构假设 → 先校验返回结构再访问深层属性
|
|
35
|
-
- 禁止精度/范围假设 → 计算前确认数值在安全范围内
|
|
36
|
-
- 禁止资源泄漏假设 → 文件/连接/cursor 等使用后必须释放
|
|
51
|
+
**DO**
|
|
52
|
+
- 🟡 超过 500 行文件：分次读取或编辑前重新读取完整文件
|
|
53
|
+
- 🟡 上下文压缩恢复后：`git status` → 重读 proposal/design/tasks → 对照 design 检查实现 → lint + typecheck → 继续
|
|
54
|
+
- ⚪ 超过 10 条消息后，编辑任何文件前强制重新读取
|
|
37
55
|
|
|
38
|
-
|
|
56
|
+
**DO NOT**
|
|
57
|
+
- 禁止跨阶段跳步（explore→apply→verify→e2e 各阶段由用户触发）
|
|
58
|
+
- 禁止跨 change 改动：`/opsx:apply <X>` 期间不改 `changes/<Y>/`
|
|
59
|
+
- 禁止"顺手清理"其他 open change 文件 → 告知用户，由用户决定
|
|
39
60
|
|
|
40
|
-
|
|
61
|
+
---
|
|
41
62
|
|
|
42
|
-
|
|
43
|
-
1. `git status` — 确认已改动的内容
|
|
44
|
-
2. 重读 `changes/<name>/proposal.md` + `design.md` + `tasks.md` — 确认范围、设计决策、任务状态
|
|
45
|
-
3. 对照 design.md 检查关键实现（路径、命名、目录结构）
|
|
46
|
-
4. 运行对应语言的 lint + typecheck 验证
|
|
47
|
-
5. 然后继续实施
|
|
63
|
+
## 3. 架构 Invariants
|
|
48
64
|
|
|
49
|
-
**
|
|
65
|
+
> **[项目特定]** 以下仅适用于 openspec-playwright 项目结构。WHY：这些约束一违反即产生 review 难发现的 bug。Anthropic 称其为最高杠杆的 agent 代码质量措施。
|
|
50
66
|
|
|
51
|
-
|
|
67
|
+
- 🔴 CLI 命令向 `src/index.ts` 注册，`src/commands/` 下按职责分文件
|
|
68
|
+
- 🔴 模板文件放 `templates/`，不与其他源码混放
|
|
69
|
+
- 🟡 OpenSpec change artifacts 放 `changes/<name>/`，遵循命名规范
|
|
70
|
+
- 🟡 E2E 测试生成代码放 `e2e/`（如 `e2e/auth.setup.ts`）
|
|
71
|
+
- 🔴 文档同步规则：改 `src/commands/*.ts`/`src/index.ts` 时必须同步更新 README + CHANGELOG
|
|
52
72
|
|
|
53
|
-
|
|
73
|
+
---
|
|
54
74
|
|
|
55
|
-
##
|
|
75
|
+
## 4. 工具使用
|
|
56
76
|
|
|
57
|
-
|
|
77
|
+
> WHY：工具使用方式直接影响搜索覆盖面和结果准确性。
|
|
58
78
|
|
|
59
|
-
|
|
79
|
+
**DO**
|
|
80
|
+
- 🟡 搜索要全：Grep 搜内容 + Glob 搜文件名，两者缺一不可。跳过 node_modules/vendor/__pycache__（调试依赖时除外），搜子目录时按需缩小
|
|
81
|
+
- 🟡 重命名覆盖：调用、类型、字符串、import、barrel file、测试 mock，不得假设一次覆盖
|
|
82
|
+
- ⚪ 联网调研优先 agent-reach skill
|
|
83
|
+
- 🟡 编辑 → 重新读取确认 → lint+typecheck → 任一失败则回退
|
|
84
|
+
- 🟡 变更完成告知用户可能遗漏区域，提示人工复查
|
|
60
85
|
|
|
61
|
-
|
|
86
|
+
**DO NOT**
|
|
87
|
+
- 禁止用 sed/awk/node -e/python -c 等管道命令改源码文件（跳过编辑工具验证层）
|
|
88
|
+
- 不主动推送，除非用户明确要求
|
|
89
|
+
- 不假设单次 grep 覆盖所有情况（glob 可能漏嵌套文件或非标准扩展名）
|
|
62
90
|
|
|
63
|
-
|
|
91
|
+
**REQUIRE**
|
|
92
|
+
- 使用格式化工具（ruff fmt / prettier 除外——不改语义）
|
|
93
|
+
- 密钥与 .env 不入版本控制。示例用占位符（如 `YOUR_API_KEY`）。调试日志不打印凭据
|
|
64
94
|
|
|
65
|
-
|
|
95
|
+
---
|
|
66
96
|
|
|
67
|
-
|
|
97
|
+
## 5. 大规模任务
|
|
68
98
|
|
|
69
|
-
|
|
99
|
+
> WHY：200+ 行直接修改缺乏评审，OpenSpec 工作流强制提案→设计→评审→实现。
|
|
70
100
|
|
|
71
|
-
|
|
101
|
+
- 🔴 200+ 行修改或架构变更（新增服务/API 契约/数据模型重构）必须走 OpenSpec（`/opsx:propose`），禁止直接修改
|
|
72
102
|
|
|
73
|
-
|
|
103
|
+
### 工作流参考
|
|
74
104
|
|
|
75
|
-
|
|
105
|
+
| 阶段 | 命令 | 退出条件 |
|
|
106
|
+
|------|------|---------|
|
|
107
|
+
| 提案 | `/opsx:propose` | proposal + scenarios 生成 |
|
|
108
|
+
| 实现 | `/opsx:apply` | lint + typecheck 通过 |
|
|
109
|
+
| 自审 | `/opsx:verify` | 实现匹配 design，无遗漏 |
|
|
110
|
+
| E2E | `/opsx:e2e` / `/opsx-e2e` | 测试生成 + Healer 验证通过 |
|
|
111
|
+
| 归档 | `/opsx:archive` | specs 更新，归档完成 |
|
|
76
112
|
|
|
77
|
-
|
|
113
|
+
所有阶段由用户手动触发，**AI 不自动进入下一阶段**。Superpowers（可选）：`/plugin install superpowers@claude-plugins-official`，提供对话式 spec 探索、TDD、subagent 并行实现，不改变主流程。
|
|
78
114
|
|
|
79
|
-
|
|
115
|
+
---
|
|
80
116
|
|
|
81
|
-
## 6.
|
|
117
|
+
## 6. 数据编撰禁令
|
|
82
118
|
|
|
83
|
-
|
|
119
|
+
> WHY：AI 有"填空"倾向——缺乏数据时编造看似合理的值，引入静默 bug。
|
|
84
120
|
|
|
85
|
-
|
|
121
|
+
**DO NOT**
|
|
122
|
+
- 严禁主动编撰任何数据填充代码，除非用户明确同意
|
|
123
|
+
- 编撰示例：mock 用户/邮箱/手机号、编造测试期望值、凭空出现配置默认值、假装存在的接口/字段/枚举值
|
|
124
|
+
- 不编造 URL/路径 → 引用真实来源，勿凭印象编造 endpoint/path/字段名
|
|
125
|
+
- 遇需数据的代码位必须显式询问用户
|
|
126
|
+
- 用户拒绝时，用 stub / `throw` / `return null` 显式失败，禁止静默编造
|
|
86
127
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
4. 用户拒绝提供 → 用 stub / `throw` / `return null` 让代码显式失败，**禁止**静默编造值
|
|
128
|
+
**REQUIRE**
|
|
129
|
+
- 用户同意占位 → `TODO(user)` 标注并附问询上下文
|
|
130
|
+
- 用户提供数据 → 使用真实数据
|
|
131
|
+
- 无论前后端一体还是纯前端，存在 OpenAPI/接口文档 → 查阅真实定义并标注来源（如 `// 来源: docs/api/openapi.yaml#/paths/...`）
|
|
92
132
|
|
|
93
|
-
|
|
133
|
+
---
|
|
94
134
|
|
|
95
135
|
## 7. 临时文件管理
|
|
96
136
|
|
|
97
|
-
|
|
137
|
+
- 非源码临时文件（截图、日志、heapdump 等）放项目根 `tmp/` 下
|
|
98
138
|
- 平铺，不分子目录
|
|
99
|
-
-
|
|
100
|
-
-
|
|
139
|
+
- 文件名含时间戳
|
|
140
|
+
- 超 24 小时的文件可在 commit 前删除
|