dev-guidelines

name	dev-guidelines
description	通用编码标准与各语言最佳实践，定义生产级代码的编写规范。注入任何开发者 Agent 以建立一致的质量基线——代码质量取决于遵循的标准，而非模型能力本身。
allowed-tools	bash read glob grep
metadata	{"name_zh":"开发守则","name_zh-tw":"開發守則","description_zh":"通用编码标准与各语言最佳实践，定义生产级代码的编写规范。注入任何开发者 Agent 以建立一致的质量基线——代码质量取决于遵循的标准，而非模型能力本身","description_zh-tw":"通用編碼標準與各語言最佳實踐，定義生產級程式碼的編寫規範。注入任何開發者 Agent 以建立一致的品質基線——程式碼品質取決於遵循的標準，而非模型能力本身"}

使用时机

编写或审查代码时，此技能始终生效。无需用户请求触发——它作为基线纪律自动注入。

请勿用于架构决策（使用 architect）、部署运维（使用 sysops）或非代码任务。

核心原则

代码质量 = 遵循标准，而非模型智能。

缺乏标准的模型，产出往往不一致。 遵循标准的模型，产出可预测、可维护。

语言选择

在编码前，识别目标语言并加载其特定指南：

如果用户询问...	加载参考	关键框架上下文
Python 后端	references/python.md	FastAPI / Django / Flask
Go 服务	references/go.md	标准库 / Gin / Echo
Rust 服务	references/rust.md	Actix-web / Axum
Node.js/TS 后端	references/typescript.md	Express / Fastify / NestJS
Java 服务	references/java.md	Spring Boot / Quarkus
任何语言	references/universal.md	跨领域原则

始终先加载 universal.md，然后加载语言特定参考。

质量门禁

代码交付前，必须通过以下门禁：

门禁 1：风格合规

• 遵循语言的官方风格指南（PEP 8、effective go、rustfmt 等）
• 整个代码库保持一致的命名约定
• 交付代码中没有 TODO/FIXME/HACK 注释

门禁 2：错误处理

• 每个可能失败的操作都有显式错误处理
• 错误带有上下文包装（不是简单的重新抛出）
• 没有静默吞掉错误（except: pass、空 catch 块）
• Panic/recover 或等价机制仅用于不可恢复状态

门禁 3：安全基础

• 始终验证和清理用户输入
• 没有硬编码的密钥、凭证或令牌
• SQL 查询使用参数化语句（不拼接字符串）
• 每个端点都有认证/授权检查

门禁 4：可测试性

• 函数小而单一职责，尽可能无副作用
• 依赖可注入（业务逻辑中没有全局单例）
• 公共 API 有对应的测试用例

门禁 5：性能意识

• 能 O(n) 解决的问题，不用 O(n^2)——算法选择要明显
• 热路径避免不必要的内存分配
• 运行时支持时，I/O 操作使用异步/非阻塞方式
• 最小化数据库查询（警惕 N+1 问题）

反模式（语言无关）

以下模式在任何语言中都不可接受：

反模式	原因	正确方法
复制粘贴编程	违反 DRY，双重维护	提取到函数/模块
上帝对象/类	违反 SRD，不可测试	按职责分解
魔法数字/字符串	不可读，易出错	命名常量或枚举
深层嵌套控制流	认知负荷 >7 层	提前返回，守卫子句
注释解释做什么	代码应该自解释	重命名变量/函数；只注释为什么
捕获所有异常处理器	吞掉 bug	捕获特定异常；让未知异常传播
全局可变状态	不可测试，易竞态	依赖注入，不可变数据
异步上下文中的同步 I/O	阻塞事件循环，降低吞吐	一致使用异步变体
硬编码环境值	开发环境有效，生产环境失败	配置文件，环境变量，特性开关

参考文件

每个语言参考包含：

1. 项目结构 — 标准目录布局
2. 命名约定 — 文件/类/函数/变量命名规则
3. 代码组织 — 模块/包边界，导入顺序
4. 错误处理模式 — 该语言的惯用错误处理
5. 测试标准 — 框架选择，覆盖率期望，fixture 模式
6. 安全检查清单 — 语言特定的安全陷阱
7. 性能模式 — 常见优化和反模式
8. 生态工具链 — 使用的 linter、formatter、类型检查器

编写代码前，先加载相应参考。