66 lines
3.7 KiB
Markdown
66 lines
3.7 KiB
Markdown
|
# 项目语言规范
|
|||
|
|
|
|||
|
|
> **体系编号**：`D8.1` · 域：八、AI 协作规则 · 编号体系见 `D1.1` §4.0
|
|||
|
|
> **日期**：2026-09-19 · **性质**：**强制规范**（人机协作与交付物的语言口径，开工前必读）
|
|||
|
|
> **来源**：本文件原以「`D8.1` 项目语言规范」为题**内嵌在 `开发文档\CLAUDE.md` 顶部**（与英文本的 AI 入口协议同处一文件）。按 `乙-27` / `DEC-28` 裁定「做 `D8.1-项目语言规范.md` + 三行存根」，现拆分为独立文件；`CLAUDE.md` 只留指向本文件的存根。
|
|||
|
|
|
|||
|
|
## 1. 四条硬规则（对话与全部产出）
|
|||
|
|
|
|||
|
|
| # | 规则 | 适用面 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| 1 | 所有对话、解释、建议必须使用**简体中文** | 人机对话、方案、评审意见 |
|
|||
|
|
| 2 | 代码注释必须使用中文 | `app\`、`tools\`、`tests\` 全量源码 |
|
|||
|
|
| 3 | 生成的 Commit Message 必须使用中文 | git 提交信息 |
|
|||
|
|
| 4 | 严禁出现**大段未翻译的英文技术名词** | 全部交付文档与代码注释 |
|
|||
|
|
|
|||
|
|
> **术语例外（不构成违规）**：技术标识符与命令名（`Milvus`、`pytest`、`nffund.com`、`Idempotency-Key`）、行业标准缩写（`RAG`、`RBAC`、`Embedding`、`DoS`）、库名与字段名**一律保留原文**；判定标准是**成句的英文**——整句英文描述必须译为中文。
|
|||
|
|
|
|||
|
|
## 2. AI 协作入口协议（原 `CLAUDE.md` 正文，2026-09-19 迁入）
|
|||
|
|
|
|||
|
|
### 2.1 规则优先级
|
|||
|
|
|
|||
|
|
**P0 阅读规范 → P1 项目上下文 → P2 执行规范 → P3 测试规范 → P4 输出规范**；发生冲突时按同序裁决（前者优先）。
|
|||
|
|
|
|||
|
|
| 优先级 | 文件 |
|
|||
|
|
|---|---|
|
|||
|
|
| P0 阅读 | `开发文档\ai\D8.3-01_READING_RULES.md` |
|
|||
|
|
| P1 上下文 | `开发文档\ai\D8.7-05_PROJECT_CONTEXT.md` |
|
|||
|
|
| P2 执行 | `开发文档\ai\D8.4-02_EXECUTION_RULES.md` |
|
|||
|
|
| P3 测试 | `开发文档\ai\D8.5-03_TESTING_RULES.md` |
|
|||
|
|
| P4 输出 | `开发文档\ai\D8.6-04_OUTPUT_RULES.md` |
|
|||
|
|
|
|||
|
|
### 2.2 强制工作流（禁止跳过阅读阶段直接编码）
|
|||
|
|
|
|||
|
|
理解需求 → 阅读项目 → 建立上下文 → 分析影响面 → 输出方案 → 获得确认（如需） → 实现 → 测试 → 总结。
|
|||
|
|
|
|||
|
|
### 2.3 阅读完成闸门（八问，任一答不上就继续阅读）
|
|||
|
|
|
|||
|
|
① 当前需求属于哪个模块？② 当前调用链是什么？③ 当前数据从哪里来？④ 当前数据写到哪里去？
|
|||
|
|
⑤ 当前权限在哪里校验？⑥ 当前影响哪些模块？⑦ 当前风险等级是什么？⑧ 最小修改方案是什么？
|
|||
|
|
|
|||
|
|
### 2.4 高风险区域（必须先完成风险分析，**禁止直接修改**）
|
|||
|
|
|
|||
|
|
`Docker` / `Docker Compose` / `Nginx` / 环境变量 / 数据库迁移 / 认证 / `RBAC` / 文件存储 / 后台 `Worker` / 部署脚本 / `CI`、`CD`。
|
|||
|
|
|
|||
|
|
### 2.5 编码准入条件
|
|||
|
|
|
|||
|
|
已完成：项目阅读 + 调用链分析 + 影响面分析 + 方案设计 + 明确验证方案。**缺任一项则继续阅读。**
|
|||
|
|
|
|||
|
|
### 2.6 项目哲学
|
|||
|
|
|
|||
|
|
AI 的首要职责不是写代码，而是**理解项目**：理解错误则后续全部错误，理解正确则编码只是执行。
|
|||
|
|
**`Reading First. Coding Later.`**
|
|||
|
|
|
|||
|
|
## 3. 编号与落位（2026-09-19 起）
|
|||
|
|
|
|||
|
|
| 文件 | 编号 | 位置 | 性质 |
|
|||
|
|
|---|---|---|---|
|
|||
|
|
| 项目语言规范（本文件） | `D8.1` | `开发文档\D8.1-项目语言规范.md` | 强制规范（正文） |
|
|||
|
|
| 用法说明 | `D8.2` | `开发文档\ai\D8.2-README.txt` | 说明〔`.txt` 例外，不注入编号行〕 |
|
|||
|
|
| 阅读 / 上下文 / 执行 / 测试 / 输出 | `D8.3`—`D8.7` | `开发文档\ai\` | 分层规范 |
|
|||
|
|
| 入口存根 | — | `开发文档\CLAUDE.md` | **仅三行**，指向本文件 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
**维护**：语言口径变更须改本文件并同步 `D1.1` §4.0 总表；`CLAUDE.md` 保持三行存根，**不得再在其内追加规则正文**（否则又回到「同一规范两处正文」）。
|