# 通用开发规范

本规范为跨语言的开发通用约定，约束代码产物中的文本语言、注释格式及配套开发行为。

## 1. 文本输出语言

- 异常信息、日志记录、提示语及代码输出等，原则上统一使用英文。
- 异常信息应说明「发生了什么 + 关键上下文」（编号、参数、约束等），避免拼音与中式英语。
- 日志 message 使用英文，变量经占位符输出，不得在文案中拼接中文。
- 提示语（返回调用方的 message、error message、接口响应消息、枚举与状态描述）及代码输出（打印语句、脚本输出、CLI 文案）均使用英文。
- 例外：接入 i18n 的项目，提示语按资源文件管理；项目另有明确文案约定或用户明确要求的，从其约定，但异常信息与日志保持英文。

## 2. 注释规范

**语言**

- 注释以中文为主，专业术语保留英文原文（如 DTO、SPI、OAuth、PO(Persistent) 等），不强行翻译。
- 注释应说明「为什么」，而非复述代码；不得使用拼音，不得将整句注释写作英文。
- 修改代码时须同步修改注释，尤其参数、返回值、异常及核心逻辑变化。

**格式**

- 支持文档注释的语言，应优先采用标准文档注释格式，不得以普通行注释 / 块注释替代。
- 公开 API（类、接口、公开方法 / 函数、公共常量字段）必须使用所在语言的标准文档注释；正文遵循上述语言约定（中文为主），标签、注解与参数名保持英文。
- 常见标准：Java/Kotlin 为 Javadoc / KDoc（`/** ... */`）；Python 为 Docstring（PEP 257，团队统一 Google / NumPy / reST 风格之一）；JavaScript/TypeScript 为 JSDoc / TSDoc；C# 为 XML 文档注释（`/// <summary>`）；Go 为紧邻声明上方的 doc comment；Rust 为 `///`（条目）与 `//!`（模块）；C/C++ 为 Doxygen 风格；PHP 为 PHPDoc；其余语言按各自生态标准。
- 文档注释应可被文档工具解析并生成 API 文档，不得写入与该声明无关的实现细节。

## 3. 文件系统边界

- 项目内文件写操作（增、删、改）可直接执行，无须逐项征得同意；完成后应在回复中说明操作原因（如修复 bug、按需求重构等）。
- 项目外部路径的读取允许，但须在事后说明所读文件路径与用途。
- 写入项目外部路径前，必须：
  1. 明确告知文件绝对路径与用途；
  2. 取得用户明确同意。

## 4. 依赖管理

- 未经用户同意，不得修改构建配置文件（如 `pom.xml`、`package.json`、`build.gradle`、`go.mod`、`requirements.txt` 等）。
- 添加依赖时必须说明：
  1. 依赖坐标与版本；
  2. 引入的必要性；
  3. 风险评估（安全性、维护状态等）。

## 5. 脚本管理

- 脚本语言优先选用环境中已可用的解释器（如 Git Bash、Python 等），不得为运行脚本引入新依赖（见第 4 节依赖管理）。
- 临时脚本存放于临时目录，无须持久化：项目级脚本放项目的 `.temp/` 目录，用户级脚本放系统为用户规定的临时目录。
- 可复用脚本持久化保存时，按级别选择存放位置：
  1. 项目级：项目的 `.scripts/` 目录（仅当前项目内复用）。
  2. 用户级：用户的 `.scripts/` 目录（Windows 为 `%USERPROFILE%\.scripts`，Linux/macOS 为 `~/.scripts`；可跨项目复用，但属项目外部路径，按第 3 节须先取得用户同意）。

## 6. 版本控制

- 不可逆或影响范围较大的 Git 操作（强制推送、改写提交历史、删除分支、批量回滚等）须经用户确认。
- 提交信息遵循 Conventional Commits 规范。

## 7. 交付验证

- 改动完成后应运行项目已有的测试 / 构建进行验证，未通过不得交付。
- 遵循项目既有的格式化与静态检查配置，不做与任务无关的格式重排。

## 8. 密钥管理

- 严禁将密钥（API Key、Token、密码、私钥、连接字符串等）硬编码于源码、脚本、配置示例或注释。
- 密钥应经环境变量、独立的本地配置文件（不入库）或密钥管理服务注入，代码中仅读取引用。
- `.env` 等敏感配置文件必须加入 `.gitignore`，不得提交至版本库。
- 文档、示例代码与日志不得出现真实密钥，应以占位符（如 `<YOUR_API_KEY>`）代替。
- 发现密钥泄露（误提交或误输出）时，应立即提示用户撤销并更换，不得仅删除记录。