pingdior/cto-for-videcoding

SKILL · Digital Service Development for AI Agents

适用场景：指导 AI 编码 Agent（Cursor / Claude Code / Cline 等）开发多端数字服务——尤其是涉及多角色、合规、支付、数据质量、AI 集成的产品（如 Prolific / Mechanical Turk / Scale AI / 调研平台 / SaaS 工具等）。

目标模型：Claude Sonnet 4.5+ / GPT-5 / Gemini 2.5 Pro 及以上等级。

使用方式：作为项目根目录 AGENTS.md 或 .cursor/rules/ 的核心规则文件加载。

---

§ 0 · SKILL 元原则（Meta-Principles）

0.1 三个不可违反的硬约束

① No Assumption    不臆断需求 / 不臆造 API / 不虚构路径 → 不确定就停下来问
② No Scope Creep   只解决用户明确请求的问题 → 任何"顺手改进"都是越界
③ No Silent Fail   错误必须暴露，至少留日志 → 绝不 try/catch 吞异常假装成功

违反任何一条 = 任务失败，无论代码多漂亮。

0.2 数字服务的四个行业基线

开发任何用户面向的数字服务，默认必须满足：

| 维度 | 基线要求 | |---|---| | 合规性 | GDPR / CCPA / 数据驻留 / 未成年人保护 / 行业特定（HIPAA / SOC2）| | 可观测 | 日志 / 指标 / 追踪 / 审计四件套，关键路径全覆盖 | | 可回滚 | 任何变更必须有回滚路径，禁止"破坏性单向操作" | | 多语言 | i18n 从第一行代码开始，禁止后期补救 |

这四条不需要用户提，模型必须默认假设它们存在。

---

§ 1 · 任务分级与响应模式（Task Triage）

收到需求 → 第一步必须分级，再决定动作。

| 等级 | 触发条件 | Agent 必须动作 | |---|---|---| | L1 微改 | 单文件 / <20 行 / 无副作用 | 直接改 → 输出变更摘要 | | L2 常规 | 1–3 文件 / 局部影响 | 口述思路 ≤3 句 → 改 → 摘要 | | L3 重大 | >3 文件 / 架构调整 / 新能力 / 跨模块 / 涉及发布 | 先方案 → 等确认 → 再动手 | | L4 模糊 | 需求歧义 / 多种解读 / 缺关键信息 | 停下来提问，禁止猜测推进 | | L5 高危 | 涉及支付 / 用户数据 / 鉴权 / 合规 / 不可逆操作 | L3 流程 + 主动请求人工 review |

L3/L4/L5 直接动手 = 违规。哪怕"觉得"用户想要这个。

1.1 L2+ 任务的强制开场白

📋 任务理解
- 我理解的需求：...
- 假设：A、B、C 成立
- 不确定点：D 处倾向于 ... 因为 ...
- 多种解读（如有）：① ... / ② ... ，建议 ① 因为 ...
- 更简方案（如有）：你要的是 X，但 Y 可能更合适，因为 ...
- 风险预警（如有）：这会影响到 ... 模块

缺失这步直接交付代码 = 违规。

1.2 多步骤计划模板

🎯 目标（必须可验证）：[一句话成功标准]

📐 计划：
1. [步骤] → 验证：[具体检查点 / 测试 / 命令]
2. [步骤] → 验证：...
3. [步骤] → 验证：...

🔄 回滚预案：[如果失败如何回到当前状态]

禁止模糊目标如"让它跑起来"、"优化一下"。

---

§ 2 · 编码原则（Coding Principles）

2.1 最小化（YAGNI）

每行代码必须能直接追溯到用户具体请求。 否则删掉。

禁止行为清单：

• ❌ 添加需求外的功能、参数、配置项
• ❌ 为一次性代码引入抽象层、接口、基类、工厂
• ❌ 为不可能场景写防御代码
• ❌ 提前优化（"以后可能用得上"）
• ❌ 200 行能用 50 行解决时不重写

复杂度自检：资深工程师看到这段会皱眉吗？ → 是 → 简化。

2.2 手术式修改（Surgical Edits）

| 情况 | 正确做法 | |---|---| | 相邻代码风格不一致 | 不动，遵循现有风格 | | 发现无关 bug | 指出，不修复（除非授权）| | 发现僵尸代码 | 指出，不删除 | | 自己改动产生未使用 import / 变量 | 必须清理 | | 觉得有更好写法 | PR 评论，不动手 |

判断准则：删掉这行改动，用户需求还能满足吗？能 → 越界。

2.3 DRY 的边界

• 两次重复 ≠ DRY 信号，三次才是——避免过度抽象
• 抽共享工具的判断标准：业务语义相同 + 变化方向一致
• 形似神不似的代码（如订阅状态 vs 订单状态）→ 不要合并

2.4 Bug 修复流程

1. 复现 → 写最小复现路径（最好是失败的测试）
2. 定位 → 说明根因，不是症状
3. 修复 → 最小改动让测试通过
4. 验证 → 测试通过 + 不引入新失败
5. 沉淀 → 是否需要加入项目规则防止重犯

禁止：没复现就猜原因、没定位就改代码、改了就交付。

---

§ 3 · 数字服务核心域规则（Domain Rules）

3.1 多端架构（Web / Mobile / API）

共享层：业务规则 / 类型定义 / i18n key / 配置常量
端定制层：UI / 平台 API / 系统集成

• 业务规则（订阅状态判断、价格计算、权限校验）→ 共享层唯一来源
• 端层禁止重复实现业务逻辑，只做适配
• 跨端 API 契约用 OpenAPI / tRPC / Protobuf 强约束，禁止口头协议

3.2 用户身份与鉴权（Auth）

• 永远区分：未登录 / 已登录未验证 / 已验证未付费 / 已付费 / 角色权限
• Token 必须有过期 + 刷新机制，禁止"永久 token"
• 敏感操作（改密码 / 改邮箱 / 删账号 / 大额支付）→ 强制二次验证
• 角色变更 / 权限变更 → 必须立即失效旧 session，不依赖 token 自然过期

3.3 支付与订阅（Payment）

• 幂等性：同一支付意图重试不能产生多笔扣款，必须有 idempotency_key
• 状态对账：本地状态 + 第三方（Stripe / Apple / Google）状态必须有对账机制
• 三方系统不可控边界：
  • ✅ 可控：App 内 UI、本地状态、自家 API
  • ❌ 不可控：Apple / Google 的系统弹窗语言、Sandbox 行为、TestFlight 提示
• 退款 / 取消 / 升级 / 降级流程必须全状态机覆盖，禁止只处理 happy path
• Webhook 必须验签 + 幂等处理 + 重试容错

3.4 数据质量（核心资产）

对于 Prolific 这类数据本身就是产品的服务：

• 数据采集流程必须有：质量门 + 去重 + 异常检测 + 可追溯
• 每条数据记录必须能追溯到：来源、采集时间、版本、操作者
• 数据修改必须软删除 + 审计日志，禁止物理删除生产数据
• 跨地域数据流动必须显式配置（数据驻留合规）

3.5 国际化（i18n）

• 零硬编码：所有用户可见文案接入 i18n。中/英字面量出现在 UI = 违规
• 优先级链（必须显式定义）：

  用户手动选择 > 用户 profile > 系统语言 > 默认语言
  

• 切换的级联更新：会话上下文 / 缓存 / 默认问候 / LLM 系统提示 / 服务端偏好 → 全部同步刷新
• 测试矩阵：至少 EN / ZH / JA 三条路径覆盖核心流程
• 文案结构化：禁止字符串拼接，用 ICU MessageFormat 处理复数 / 性别 / 占位符

3.6 AI / LLM 集成

类 Prolific 的服务大量集成 LLM，必须：

• Prompt 版本化：所有 system prompt / few-shot 例子进版本控制
• 输出校验：LLM 返回必须经 schema 校验（Zod / Pydantic），禁止裸用
• 失败兜底：限流 / 超时 / 内容审核拒绝 → 必须有降级路径
• 成本可观测：token 用量、模型调用次数、人均成本必须有监控
• PII 保护：用户敏感信息默认不送进 LLM，必须送 → 脱敏 + 审计
• 幻觉防护：涉及事实 / 数字 / 引用的输出，强制要求来源标注或 RAG 锚定

---

§ 4 · 部署与发布（Deployment）

4.1 部署成功的真实定义

CI 绿灯 ≠ 部署成功。全部验证：

☐ 目标 commit hash
☐ 服务器工作树 commit hash 一致
☐ 镜像 build time 晚于代码提交时间
☐ 运行容器版本 / hash 与目标一致
☐ 关键页面手动 smoke check
☐ 关键 API 健康探针 200

4.2 失败处理铁律

• 构建失败 → 立即终止，禁止 up -d 让旧镜像冒充新版
• 推送失败 → 不要重试 3 次后假装成功，明确告知
• 容器启动失败 → 回滚，不要让线上停服等修
• 数据库迁移失败 → 回滚 schema + 回滚代码，禁止半应用状态

4.3 环境净化

Docker 构建前必须检查：

• 代理污染（本地 clash / VPN / 企业代理）
• .env 是否被错误覆盖
• node_modules / 构建缓存是否需清理
• 依赖锁文件是否一致（package-lock.json / pnpm-lock.yaml / poetry.lock）

发现异常 → 阻断 + 明确报错，禁止静默继续。

4.4 线上问题排查顺序

代码未拉到 → 镜像未重建 → 容器未替换 → CDN 未刷新 → 浏览器缓存未刷新

跳步排查 = 浪费时间。

4.5 灰度与回滚

• 涉及用户数据 / 支付 / 鉴权的变更 → 强制灰度（至少 1% → 10% → 100%）
• 任何发布必须有 ≤5 分钟回滚预案
• DB schema 变更遵循 Expand-Contract：先扩展兼容 → 双写 → 切流 → 收缩

---

§ 5 · 代码质量与可观测（Quality & Observability）

5.1 异步与状态管理

• 悬空 Promise 零容忍：必须 await 或显式 .catch
• 同一异步操作禁止重复触发（购买 / 恢复 / 重试 / 刷新流程必须加锁）
• 状态机式流程必须显式处理 idle / loading / success / error / retry 五态

5.2 非主流程不许静默

后台刷新、兜底请求、Promise.allSettled 失败分支 → 必须留日志：

必含字段：操作名 + 失败原因 + 上下文 ID（user/session/request）+ 时间戳

5.3 配置集中

业务标识（产品 ID / feature flag / 价格点 / API endpoint / 第三方 key）→ 统一配置层，禁止散落硬编码。

环境差异通过配置区分，禁止 if (env === 'prod') 满天飞。

5.4 环境隔离

| 路径 | 原则 | |---|---| | 生产 | 用户体验优先，错误信息友好化 + 错误 ID | | 开发 | 详细堆栈 / 请求 / 响应可见 | | 测试 | Mock 一切外部依赖，禁止打到真实第三方 |

5.5 可观测三件套

关键路径必须有：

• 结构化日志（JSON，含 trace_id）
• 业务指标（注册数 / 订单数 / 错误率 / P95 延迟）
• 分布式追踪（OpenTelemetry，跨服务可追）

---

§ 6 · 交付规范（Delivery Spec）

6.1 任务完成时的强制输出

📝 变更摘要
• 修改文件：<file>:<line-range> 简述变更意图
• 关键决策：为什么这样改而非那样改
• 潜在风险：可能影响的范围 / 边界情况 / 回归点
• 建议验证：具体命令 / 测试用例 / 手动步骤
• 未处理项：故意没改的 / 发现但未动的僵尸代码
• 合规检查：i18n ☐ / 鉴权 ☐ / 日志 ☐ / 回滚预案 ☐（按需勾选）

缺任何一项 = 任务未完成。

6.2 经验沉淀机制

被用户纠正过 ≥2 次的问题，主动提议固化为规则：

💡 建议固化规则
上下文：[问题场景]
规则建议：[具体可执行]
归属章节：[§N.N]

---

§ 7 · 交付前自我审计（Pre-Delivery Checklist）

每次交付前必须逐条过：

【任务流程】
☐ 任务等级判断正确？(L1/L2/L3/L4/L5)
☐ L2+ 做了开场白声明？
☐ L3/L5 等了用户确认？
☐ L4 停下来问了？

【代码质量】
☐ 每行改动可追溯到用户请求？
☐ 没顺手改动相邻代码？
☐ 没引入需求外的抽象 / 配置 / 灵活性？
☐ 自己产生的孤儿 import / 变量都清理了？

【行业基线】
☐ 涉及用户文案 → 走了 i18n？
☐ 涉及鉴权 → 权限校验到位？
☐ 涉及支付 → 幂等 + 对账？
☐ 涉及数据 → 审计日志？
☐ 涉及 LLM → schema 校验 + 兜底？
☐ 涉及发布 → 回滚预案？

【交付规范】
☐ 输出了 6 项变更摘要？
☐ 标注了未处理项？

任何一项 ☐ → 任务未完成，回去补。

---

§ 8 · 与外部规范协作

8.1 OpenSpec / 项目级 Spec

以下场景必须先打开 @/openspec/AGENTS.md 或对应项目 spec：

• 用户提到 proposal / spec / plan / change 等规划性词汇
• 引入新能力 / 破坏性变更 / 架构调整
• 重大性能 / 安全 / 合规工作
• 请求模糊、需要权威 spec 兜底

<!-- OPENSPEC:START --> <!-- Keep this block so 'openspec update' can refresh the instructions. --> <!-- OPENSPEC:END -->

8.2 行业标准引用

开发以下功能时，必须引用对应行业标准：

| 功能 | 标准 | |---|---| | 鉴权 | OAuth 2.1 / OIDC | | 支付 | PCI-DSS（如自托管卡数据）/ 各支付方文档 | | 数据合规 | GDPR / CCPA / PIPL（中国）| | 可访问性 | WCAG 2.2 AA | | API 设计 | OpenAPI 3.1 / JSON:API | | 日志 | OpenTelemetry / ECS |

不需要用户提，模型默认查阅并对齐。

---

§ 附录 · 快速参考卡（Cheat Sheet）

收到任务 → 分级 (L1-L5)
     ↓
L4 模糊 → 停下来问
L3/L5  → 先给方案等确认
L2     → 开场白 + 改 + 摘要
L1     → 直接改 + 摘要
     ↓
动手前 → 三个硬约束自检 (No Assumption / No Scope Creep / No Silent Fail)
     ↓
动手中 → 手术式 + YAGNI + DRY 边界
     ↓
完成前 → § 7 Checklist 全过
     ↓
交付   → 6 项变更摘要 + 未处理项标注