0xkangl Code Conventions
横切工程规范的统一索引。按任务与文档 Scope 加载相关规范，不要求每次读取全部文档；沿用项目明确约定，不能将参考示例视为操作授权。
通用规范（Universal）
与技术栈无关，按实际涉及的关注点选用。
| 关注点 | 文档 | Scope | Description |
|---|---|---|---|
| 编码风格 | references/coding-style.md | 所有模块 | 语言无关的命名、文件组织、注释哲学、代码味道；行为准则见 engineering-guidelines skill |
| 设计模式 | references/patterns.md | 所有模块 | 分层架构、Repository、依赖注入、统一响应封套、用类型表达不变量 |
| 安全基线 | references/security.md | 所有模块 | 密钥、边界校验、注入/XSS/CSRF、认证授权、依赖审计；各语言 *-security 在此扩展 |
| HTTP API 设计 | references/http-constitution.md | 所有 HTTP 服务 / API | 方法选择、状态码、响应结构、分页、排序、时间格式、版本化、Accept-Language 内容协商与 locale 归一化 |
| 配置 / 密钥 | references/configuration.md | 所有模块 | 环境变量命名、缓存/队列双前缀、模块间 internal token、密钥与 HKDF 派生、JWT TTL（web 短时效）、第三方 stub 模式、服务端口 |
| 日志 / 可观测性 | references/observability.md | 所有模块 | 结构化日志（JSON/text）、日志级别判据、逻辑位置、traceId 上下文贯穿、分级脱敏、CLI/批处理日志、命名约定 |
| 测试 | references/testing.md | 所有模块 | 测试分类、AAA 结构、命名、mock 哲学、覆盖率目标、集成测试 |
| 项目文档 | references/project-documentation.md | 初始化或维护项目文档 | 指令入口与内容归属、README 真实性、进度记录和按需同步 |
| 仓库 / Git 工作流 | references/repository-workflow.md | 初始化仓库、配置 CI、维护忽略规则或执行 Git 写操作 | 分支约定、操作授权、提交范围、GitHub Actions 持续集成、忽略文件与配置模板 |
| 提交信息 | references/conventional-commits.md | 所有模块 | Git 提交信息规范：type、scope、格式 |
| 错误码 | references/error-codes.md | 所有 API | 业务错误码注册表：码段划分、{code, message, details} 信封 |
| 容器 / Docker | references/docker.md | 所有容器化模块 | Dockerfile 规范：多阶段构建、层缓存顺序、非 root 用户、.dockerignore、必要注释 |
| 部署 / 发版 | references/deployment.md | 所有可部署模块 | 发版前置资料清单、配置文件 [env] 与平台 secret 的归属判据、发版执行顺序与验证/回滚、Fly.io 与 Cloudflare(wrangler + API token) 两套方案 |
| 数据库迁移 | references/db-migrations.md | 所有带持久化的模块 | 生产只前滚、DDL/DML 分离、加列/加索引的锁影响、expand-contract 改名与删除、分批可重入回填、破坏性变更判定 |
Go 专项规范（references/golang/）
在通用规范之上扩展 Go 技术栈。
| 文档 | Scope | Description |
|---|---|---|
| references/golang/go-project.md | 所有 Go 后端服务 | 项目结构：目录布局、分层架构 |
| references/golang/go-style.md | 所有 Go 后端服务 | 风格与惯用法：命名、控制流、错误、接口、并发（基于 Effective Go） |
| references/golang/go-error-handling.md | 所有 Go 后端服务 | 错误处理：HTTPError 接口、AppError 载体、分层错误流、堆栈捕获、单一响应出口 |
| references/golang/go-tools.md | 所有 Go 后端服务 | 开发工具：air、golangci-lint、goimports、govulncheck、migrate、配置文件、Makefile 目标 |
| references/golang/go-testing.md | 所有 Go 后端服务 | Go 测试：表驱动测试、httptest、build tag、接口 mock、覆盖率命令 |
| references/golang/go-validation.md | 所有 Go 后端服务 | 输入校验：库选型、字段规则、错误格式、自定义校验器 |
| references/golang/go-security.md | 所有 Go 后端服务 | 安全：密钥、SQL 参数化、context 超时、SSRF/路径穿越、gosec/govulncheck、错误暴露 |
参考配置（normative 示例，非规范文档）：references/golang/examples/ 存放 Go 后端的标准配置样例（.air.toml、.golangci.yml、sqlc.yaml）。采用 Go 技术栈时复制到服务仓库根目录；见 go-tools.md §2。
语言 / 框架专项规范
在通用规范之上扩展各技术栈。每个目录提供四件套：-style（风格与惯用法）、-tools（工具链）、-testing（测试）、-security（安全）。Go 见上方独立章节（更细的七篇）。
JavaScript 并入
typescript/：JS ⊂ TS，ts-style.md含「JavaScript 文件（JSDoc / 纯运行时）」子节，不单列javascript/。
| 技术栈 | 目录 | 四件套 |
|---|---|---|
| Python | references/python/ |
style · tools · testing · security |
| TypeScript / JavaScript | references/typescript/ |
style · tools · testing · security |
| Rust | references/rust/ |
style · tools · testing · security |
| React | references/react/ |
style · tools · testing · security |
| Flutter / Dart | references/flutter/ |
style · tools · testing · security |
React 建在 TypeScript 之上，其文档相对互链 references/typescript/。
相关 Skill
- 规约驱动开发流程（spec-first、spec 划分/所有权、跨模块 plan 拆分、spec 索引维护）属于 polyrepo 工作区规范，见各项目
<project>-spec-center/AGENTS.md（由agents-scaffold模板生成）；本 skill 的 references/testing.md 承载其实现阶段的 TDD workflow 与测试细则。 - 工程行为规范（think-before-code、simplicity-first、surgical-changes、root-cause reasoning 等 LLM/agent 编码行为准则）不在本 skill 内，见独立 skill
engineering-guidelines。