项目规则体系
Nexus 通过一套规则文件约束 Coding Agent 与人类的协作，保证代码风格一致、架构边界清晰、AI 行为可预期。规则散落在 CODING.md（项目根）与 .claude/rules/ 中。
CODING.md（代码风格与命名规范）
项目根的 CODING.md 是 AI 必读的编码规范，要点：
命名原则
- 见名知意：名称清晰表达职责，避免无意义缩写。
- 动词 + 名词：函数名以动词开头（如
createUser、validateEmail）。 - 布尔量用语义前缀：
isValid、hasPermission、canEdit。
文件命名
| 类型 | 约定 |
|---|---|
| 页面 | 小写或 kebab-case（login.vue、user-profile.vue）；默认页 index.vue |
| 基础 UI 组件 | UiButton.vue、UiInput.vue |
| 业务组件 | FeatureName.vue |
| 布局组件 | default.vue、user.vue |
| API 路由 | <resource>.<method>.ts（users.get.ts、users.post.ts） |
| Composables | camelCase，以 use 开头（useAuth.ts） |
代码风格
- TypeScript 优先，新文件用
.ts/.vue。 - 组合式 API +
<script setup>。 - 单个函数不超过 60 行，超过则拆分。
- 嵌套不超过 3 层，优先提前返回。
- 不硬编码密钥与敏感信息，统一用环境变量。
TypeScript 约定
- 优先用
interface定义对象形状。 - 函数返回类型显式声明。
- 避免
any，必要时用unknown。
导入顺序
- 外部库 → 2. 框架/工具模块 → 3. 项目内部模块 → 4. 相对路径导入。
注释
- 不写解释「代码行为」的注释（代码应自解释）。
- 只写解释「为什么」的注释，复杂业务逻辑前写简短说明。
.claude/rules/ 规则文件
细粒度规则文件，按主题拆分（示例）：
- 编码质量规范（如函数长度、嵌套限制）
- Spec 工作流与
CONTEXT.md规范 - 密码哈希规范（RSA 传输 + bcrypt 存储）
- 系统初始化规范（默认管理员、迁移）
- 双 schema / 迁移同步规范
CONTEXT.md 状态管理
- 📋 链接行是唯一的「规划状态」标志：有 📋 = 已规划，无 📋 = 未规划。
- Sprint 归档后更新
CONTEXT.md，保持状态与.oms/实际产物一致。
工程铁律（摘要）
- 依赖方向单一：业务扩展优先落在
modules/<name>/，模块不反向依赖主应用细节。 - 响应格式统一：API 返回统一结构（见 API 文档）。
- 软删除策略：需要保留历史的记录采用软删除。
- 接口分层：API 路由 → 工具/服务 → 数据访问，职责清晰。