120 lines
4.4 KiB
Markdown
120 lines
4.4 KiB
Markdown
|
# 立交桥项目规则
|
|||
|
|
|
|||
|
|
## 项目定位
|
|||
|
|
|
|||
|
|
立交桥处于从 Demo 向生产级产品重构的阶段。这里的默认标准不是“功能能跑”，而是“能长期稳定上线、可维护、可观测、可扩展、可审计”。
|
|||
|
|
|
|||
|
|
任何改动都应优先服务于生产质量提升：稳定性、性能、安全性、可维护性、可验证性。演示型写法、一次性修补和无法长期维护的捷径都应谨慎对待。
|
|||
|
|
|
|||
|
|
## 根级工作原则
|
|||
|
|
|
|||
|
|
1. 生产主链路优先。
|
|||
|
|
只要一个能力没有接进真实运行主链路、没有验证关键路径、没有覆盖错误场景，就不要轻易定义为“已完成”。
|
|||
|
|
|
|||
|
|
2. 先澄清影响面，再改。
|
|||
|
|
立交桥包含多个子模块。修改前先识别影响的是哪个边界：`gateway/`、`internal/`、`platform-token-runtime/`、`supply-api/`、`sql/`、`scripts/`、`tests/`。
|
|||
|
|
|
|||
|
|
3. 质量闭环优先于代码数量。
|
|||
|
|
优先补齐验证、接口契约、异常处理、日志与健康检查，而不是仅追求功能增量。
|
|||
|
|
|
|||
|
|
4. 最小必要改动。
|
|||
|
|
生产级重构要控制变更半径。优先做局部可验证优化，而不是大范围重写。
|
|||
|
|
|
|||
|
|
## 模块协作规则
|
|||
|
|
|
|||
|
|
- 根目录 `AGENTS.md` 负责全局工程目标、质量标准和交付口径。
|
|||
|
|
- 如果某个子目录存在更具体的上下文文件，进入该子目录后必须叠加遵守。
|
|||
|
|
- 当前已知局部规则文件：
|
|||
|
|
- [CLAUDE.md](/home/long/project/立交桥/supply-api/CLAUDE.md)
|
|||
|
|
|
|||
|
|
尤其在 `supply-api/` 下工作时，必须同时遵守该文件中的 Go、审计、健康检查、错误处理与接口规范。
|
|||
|
|
|
|||
|
|
## 默认工作流
|
|||
|
|
|
|||
|
|
### 1. 接任务先判断类型
|
|||
|
|
|
|||
|
|
- 缺陷修复：先复现，再定位根因，再补验证
|
|||
|
|
- 重构优化：先确定是否触及公共契约、数据库、接口行为
|
|||
|
|
- 新能力开发：先定义边界、非目标、失败处理和验证策略
|
|||
|
|
- 文档完善：必须围绕真实运行主链路组织，而不是只写静态介绍
|
|||
|
|
|
|||
|
|
### 2. 对每项改动至少回答
|
|||
|
|
|
|||
|
|
- 改的是什么问题
|
|||
|
|
- 根因是什么
|
|||
|
|
- 影响哪些模块和接口
|
|||
|
|
- 有哪些风险和回归点
|
|||
|
|
- 如何验证主路径与失败路径
|
|||
|
|
|
|||
|
|
## 质量门槛
|
|||
|
|
|
|||
|
|
### 稳定性
|
|||
|
|
|
|||
|
|
- 关键路径要有明确错误处理
|
|||
|
|
- 不能依赖静默失败或“日志里写一下就算处理”
|
|||
|
|
- 外部依赖异常时，必须明确 fail-open 或 fail-closed 策略
|
|||
|
|
|
|||
|
|
### 性能
|
|||
|
|
|
|||
|
|
- 涉及核心路径时，关注响应时间、并发竞争、数据库访问次数、缓存命中和超时边界
|
|||
|
|
- 性能优化必须建立在测量或明确瓶颈判断上，不做拍脑袋优化
|
|||
|
|
|
|||
|
|
### 安全
|
|||
|
|
|
|||
|
|
- 不暴露内部实现细节、敏感数据、密钥和隐私字段
|
|||
|
|
- 审计、鉴权、幂等、配额、状态机类改动要格外谨慎
|
|||
|
|
- 高风险默认拒绝“假成功”
|
|||
|
|
|
|||
|
|
### 可维护性
|
|||
|
|
|
|||
|
|
- 命名、接口、日志、错误码、迁移脚本要保持一致
|
|||
|
|
- 不引入一次性“补丁风格”代码路径
|
|||
|
|
- 复杂逻辑必须让下一位维护者能读懂
|
|||
|
|
|
|||
|
|
## 测试与验证
|
|||
|
|
|
|||
|
|
### 完成标准默认包含
|
|||
|
|
|
|||
|
|
- 至少一条主路径验证
|
|||
|
|
- 至少一条关键失败路径验证
|
|||
|
|
- 如涉及公共接口、存储、并发、审计、权限或计费，必须提高验证强度
|
|||
|
|
|
|||
|
|
### 不算完成的情况
|
|||
|
|
|
|||
|
|
- 代码写了，但主链路未接入
|
|||
|
|
- 只过了编译，没有跑关键验证
|
|||
|
|
- 只测了 happy path，没有测约束/异常/冲突场景
|
|||
|
|
- 只写了文档或注释，没有修复行为本身
|
|||
|
|
|
|||
|
|
## 目录级关注点
|
|||
|
|
|
|||
|
|
- `gateway/`：协议边界、鉴权、路由、可观测性、退化策略
|
|||
|
|
- `internal/`：领域边界、内部服务、公共库稳定性
|
|||
|
|
- `platform-token-runtime/`：运行时状态、令牌/资源约束、异常恢复
|
|||
|
|
- `supply-api/`：遵守子目录局部规则，重视契约和审计
|
|||
|
|
- `sql/`：迁移安全、兼容性、回滚路径
|
|||
|
|
- `scripts/`：部署/运维脚本幂等性与可重复执行
|
|||
|
|
- `tests/`：优先覆盖真实风险点，不追求无意义覆盖率
|
|||
|
|
|
|||
|
|
## 文档要求
|
|||
|
|
|
|||
|
|
- 记录真实系统行为，而不是理想化状态
|
|||
|
|
- 部署、排障、接口、重构说明应围绕实际操作路径组织
|
|||
|
|
- 对未完成能力要明确标注状态，避免误导为“已经上线可用”
|
|||
|
|
|
|||
|
|
## 禁止事项
|
|||
|
|
|
|||
|
|
- 不要把 Demo 级实现包装成生产完成
|
|||
|
|
- 不要用“大概可用”替代验证
|
|||
|
|
- 不要在没有迁移与回归考虑时随意调整接口或数据结构
|
|||
|
|
- 不要为了短期推进牺牲长期可维护性，除非明确标注为临时方案
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
<claude-mem-context>
|
|||
|
|
# Memory Context
|
|||
|
|
|
|||
|
|
# [立交桥] recent context, 2026-04-25 11:41pm GMT+8
|
|||
|
|
|
|||
|
|
No previous sessions found.
|
|||
|
|
</claude-mem-context>
|