Codex Release Bot
63 lines
2.6 KiB
Plaintext
63 lines
2.6 KiB
Plaintext
---
|
|
description: 完美实现原则 — 禁止降级/妥协/技术债；设计文档与技术文档先行；每次修改写 changelog
|
|
alwaysApply: true
|
|
---
|
|
|
|
# 完美实现与文档纪律
|
|
|
|
## 实现标准（强制）
|
|
|
|
**所有设计和实现都必须是完美实现。**
|
|
|
|
- ❌ **不允许为了实现而实现** — 每一行代码、每一个接口必须有明确目的，达到项目既定的安全、架构与质量标准
|
|
- ❌ **不允许降级实现** — 不得以「先用着」「以后再改」为由降低安全、性能、可维护性或用户体验
|
|
- ❌ **不允许妥协实现** — 发现问题必须根治，不得用绕过、静默吞错、硬编码掩盖代替修复
|
|
- ❌ **不允许留技术债** — 不得留下 TODO/FIXME/「临时方案」延后处理；当场能修必须当场修
|
|
- ✅ **无法完美实现时必须停下** — 与用户沟通并确认替代方案后，才能换方案；不得擅自从权或自行降级
|
|
|
|
## 文档纪律（强制）
|
|
|
|
### 设计文档
|
|
|
|
- 所有**新功能、架构变更、非平凡重构**必须先有设计文档，再写代码
|
|
- 设计文档路径：`docs/design/specs/YYYY-MM-DD-<topic>-design.md`
|
|
- 设计文档至少包含：背景与目标、方案对比、选定方案及理由、接口/数据模型、安全与性能约束、验收标准
|
|
|
|
### 技术文档（开发前）
|
|
|
|
- 开发前输出技术文档（实施说明），路径：`docs/design/plans/YYYY-MM-DD-<topic>.md` 或 `docs/reports/<step>/engineering-report.md`
|
|
- 技术文档至少包含：涉及文件清单、实现步骤、依赖与配置变更、测试要点、回滚方式
|
|
- 项目里**已有模块但缺文档的，在改动时一并补全**，不得只改代码不留档
|
|
|
|
### Changelog（每次修改）
|
|
|
|
- **每一次**有意义的代码或配置修改，必须在 `docs/changelog/` 新增或更新记录
|
|
- 命名：`YYYY-MM-DD-<简短主题>.md`
|
|
- 每条记录至少包含：日期、变更摘要、动机、涉及文件、是否需迁移/重启、验证方式
|
|
- 禁止把 changelog 写在 commit message 里代替项目文档
|
|
|
|
## 执行顺序
|
|
|
|
```
|
|
需求确认 → 设计文档 → 技术文档 → 实现 → 测试验证 → changelog →（必要时）更新 CLAUDE.md/AGENTS.md
|
|
```
|
|
|
|
## 禁止示例
|
|
|
|
```python
|
|
# ❌ 技术债
|
|
# TODO: fix later
|
|
pass # workaround
|
|
|
|
# ❌ 降级
|
|
except Exception:
|
|
return None # 静默失败
|
|
|
|
# ❌ 无文档直接大改
|
|
# （新增整模块却无任何 docs/design 或 docs/changelog 记录）
|
|
```
|
|
|
|
## 允许的唯一例外
|
|
|
|
经用户**明确书面确认**后，方可采用非完美方案；须在 changelog 中记录例外原因、影响范围与后续补齐计划。
|