---
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 中记录例外原因、影响范围与后续补齐计划。