personal-dev-guard

Personal Dev Guard / 个人开发守门规范

这是一个中文指令型 Skill。它的本体是这份 Markdown 文档，而不是自动评分脚本。

使用者读取本规范后，应按用户的个人高级开发标准进行代码开发和代码审查。这里的重点不是部署、排障、工具调用礼仪，也不是形式化流程检查，而是判断一份代码是否清晰、可读、克制、可维护，是否像高级开发者写出来的代码。

1. 短版核心规范

开发和审查代码时，优先遵守以下原则：

1. 长期工程质量优先。不能只追求暂时能跑、暂时能实现、最小改动；方案必须符合项目既有规范，能长期维护、长期演进。
2. 可读性优先。代码首先要能顺着读懂，主流程要连贯，不要让读者在一堆小函数之间来回跳转。
3. 反对补丁味。不要为了修一个点硬塞特殊判断、flag、临时分支，让代码长期补丁化。
4. 反对炫技抽象。抽象必须来自真实需求，不为了设计感、层级感、模式感而抽象。
5. 项目规范优先。开发前要尊重现有目录结构、接口边界、命名风格、数据模型、错误处理、测试方式和发布约定；不要做一处可用、全局不一致的改动。
6. 复杂度应该来自业务本身，而不是框架、helper、接口、目录层级或设计模式额外放大出来的复杂度。
7. 核心流程需要中文注释。注释重点解释为什么、业务原因、设计取舍、坑点和非显然约束。
8. 测试应该覆盖真实风险，并且测试代码本身也要可读，像业务行为文档，而不是复杂 mock 工程。
9. Go 项目优先简单直接：少做 Java 式机械分层，不提前定义 interface，不为了 mock 污染业务结构。
10. 泛型默认克制使用：能用普通函数、明确类型或具体结构表达清楚的，就不要上泛型；只有真实多类型复用能明显减少重复并保持可读时才使用。
11. any 不算泛型，但也要克制：边界层解析动态 JSON 可以用，业务内部优先转成明确 struct、具体类型或小结构，避免把字段契约藏进运行时。
12. Review 时优先看：是否符合长期规范性和项目规范，主流程是否连贯，有没有补丁味和炫技抽象，测试/验证是否覆盖风险，改动范围是否形成完整闭环。
13. 包和目录按稳定职责与共同变更原因组织；既不要为了架构感机械拆包，也不要把多个独立能力长期堆进一个大包或 God Object。
14. 测试不能反向污染生产设计。不得仅为了测试方便，在生产代码中新增职责不合理的方法、接口、导出符号、setter/getter、hook，或放宽字段和方法可见性；生产 API 和模块边界必须在没有测试需求时也成立。

如果因为现实约束违反核心偏好，必须在 Review 或交付说明中说清楚：为什么违反、替代方案是什么、风险是什么、后续是否需要修正。

2. 规范定位

本规范约束的是代码开发质量，不是 AgentDock 运维流程。

它应该用于：

• 新增功能、修复 bug、重构、清理代码。
• Go 项目开发，尤其是服务端、CLI、工具类项目。
• 其他语言项目中的通用可读性、可维护性和测试判断。
• 开发后的代码 Review 和 debrief。

它不重点覆盖：

• Docker 部署、反代、证书、服务排障。
• iOS/watchOS 安装签名流程。
• 工具调用前后如何汇报的细节。
• 自动化评分、静态分析或代替测试工具。

这份规范不是要求所有代码都写成一种形状，而是帮助开发者始终回答一个问题：未来接手这段代码的人，能不能顺着读懂、放心修改、快速定位问题？

当“最小改动”和“长期正确”冲突时，不能默认选择最小改动。应该优先选择符合项目规范、能形成完整闭环、未来维护成本更低的方案；如果只能先临时处理，必须说明临时性、风险和后续正式方案。

3. 高级开发者判断标准

高级开发者不是把代码写得复杂，而是把真实复杂度控制在可读、可定位、可维护的范围里。

优先级如下：

1. 主流程可读，读者能顺着理解业务链路。
2. 方案符合项目既有规范和长期演进方向，不为了暂时可用破坏一致性。
3. 代码没有明显补丁味、临时味和硬塞特例。
4. 抽象克制，不为了看起来高级而制造层级。
5. 错误路径、边界条件和状态变化清楚可见。
6. 测试或验证覆盖本次改动真正的风险。
7. 改动范围服务当前目标，同时足以把功能、数据、接口、前端、测试和文档等相关闭环补齐。

不高级的代码通常有这些味道：

• 为了短函数把主流程拆散，读代码需要频繁跳转。
• 为了一个小需求引入过多 interface、manager、processor、adapter、factory。
• 为了快速修复硬塞特殊 case，没有说明原因、影响和退出条件。
• 错误被吞掉、被模糊包装，或者只打印日志后继续。
• 业务对象含义不清，充斥 map、any、万能 DTO、泛名 helper。
• 测试比业务代码还难读，mock 和 fixture 成为新的复杂度来源。
• 为了快或“少改点”，只修表面现象，不处理同一业务链路里的规范、一致性和闭环问题。