---

中文版 – AI 修改现有代码的统一规范

目的：
提供一套严谨、全面的准则，确保 AI 助手在扩展或修复现有代码时，不引入架构漂移、风格不一致或技术债务。

1. 修改前先全面理解

1.1 宏观阅读，而非局部

跟踪调用链和模块边界，了解候选代码与系统其它部分的互动。

1.2 建立心智模型

在动手前，先形成简要的内部概要（类层次、控制流程、数据流程）。

1.3 如信息缺失，则提问

若关键上下文缺乏，再向用户发问；否则默认保守处理。

2. 遵循既有架构与风格

2.1 架构连贯性

复用现有层次、模式和扩展点，禁止无授权就引入新框架或新范式。

2.2 风格一致性

严格遵守项目编码规范（命名、缩进、文档字符串格式、错误处理习惯等）。

2.3 语言与库一致

使用当前版本的语言与标准/第三方库，不随意升级或更换。

3. 复用优先，莫再造轮子

3.1 基类、Mixin、工具函数优先

先扩展现有实现，而非复制逻辑。

3.2 修改前先搜索

查找能满足需求的现成辅助函数或常量。

3.3 统一抽象

若改动跨模块，优先设计或扩展单一共享组件，避免碎片化重复。

4. 变更应最小且内聚

4.1 最小可行差异

只修改满足需求所必需的文件和函数。

4.2 不留“僵尸”代码

删除因改动而废弃的分支、标志、变量，保持代码整洁。

4.3 原子化提交

将逻辑相关的修改归为同一提交，以便独立回滚。

5. 保持向后兼容

5.1 公共契约不可破

未经授权，不得修改对外接口（API、CLI 参数、序列化格式）。

5.2 破坏性变更时，用特性开关或适配器

5.3 提供迁移方案

若数据或配置模式有变，需附迁移脚本。

6. 充分验证

6.1 每步后编译与静态检查

6.2 补充单元/集成测试

覆盖新增分支与边界情况。

6.3 回归测试

运行既有测试，确保其他行为不变。

7. 明确记录差异

7.1 写内联注释与文档字符串

解释非显而易见的逻辑。

7.2 同步外部文档

（README、API 说明、用户手册）。

7.3 更新变更日志

概述影响、弃用点及升级指引。

8. 符合质量门禁

8.1 静态分析

（安全扫描、类型检查、圈复杂度）。

8.2 性能预算

若算法复杂度变化，需基准测试关键路径。

8.3 资源占用

确保内存、I/O、网络使用在阈值内。

9. 保持可追溯与可审查

9.1 具描述性的提交信息

（做了什么、为何、范围）。

9.2 完整的合并请求

含背景、截图/日志和测试证明。

9.3 积极响应代码评审

直至获得批准。

10. 仅在合法触发条件下行动

10.1 仅在收到需求时实现新功能

10.2 修复错误或清理技术债时可重构

同时遵守上述规则。

10.3 禁止擅自添加臆想功能或大规模风格重写

---

---

English Version – Standard for AI‑Driven Modifications to an Existing Codebase

Purpose:
Provide a rigorous, multi‑dimensional guideline so that an AI assistant can extend or correct an existing codebase without introducing architectural drift, stylistic inconsistencies, or technical debt.

1. Comprehend Before You Code

1.1 Read broadly, not just locally

Traverse call‑chains and module boundaries to see how the candidate code interacts with the rest of the system.

1.2 Confirm mental models

Produce a short internal synopsis (class hierarchy, control flow, data flow) before making any edits.

1.3 Ask clarifying questions only if critical information is missing

Otherwise proceed with conservative assumptions.

2. Honor Established Architecture & Style

2.1 Architectural continuity

Reuse existing layers, patterns, and extension points; do not introduce new frameworks or paradigms unless explicitly requested.

2.2 Stylistic fidelity

Follow the project’s code conventions (naming, spacing, docstring format, error handling idioms, etc.).

2.3 Language & library parity

Prefer the same language version and core libraries already in use.

3. Prefer Reuse Over Reinvention

3.1 Leverage base classes, mix‑ins, utilities

Extend or parameterize them rather than duplicating logic.

3.2 Search before writing

Scan for existing helpers or constants that satisfy the new requirement.

3.3 Shared abstractions

If enhancement spans modules, create or extend a single shared component rather than sprinkling near‑duplicate code.

4. Make Minimal, Cohesive Changes

4.1 Smallest viable diff

Touch only the files and functions necessary to meet the requirement.

4.2 No orphaned code

Remove obsolete branches, flags, and variables created by the change; keep the codebase lean.

4.3 Atomic commits

Group logically related edits together so they can be reverted independently.

5. Preserve Backward Compatibility

5.1 Public contracts

Do not change published interfaces (APIs, CLI flags, serialized formats) unless explicitly directed.

5.2 Feature toggles or adapters when breaking changes are unavoidable

5.3 Migration path

Supply data‑ or config‑migration scripts if schemas evolve.

6. Validate Thoroughly

6.1 Compile & lint after every significant step

6.2 Extend unit/integration tests

Cover new branches and edge cases.

6.3 Regression suite

Run existing tests to confirm unchanged behavior elsewhere.

7. Document the Delta

7.1 Inline comments & docstrings

For non‑obvious logic.

7.2 Update external docs

(README, API spec, user manuals) to reflect new behavior.

7.3 Changelog entry

Summarize impact, deprecations, and upgrade notes.

8. Conform to Quality Gates

8.1 Static analysis

(Security scanners, type checkers, cyclomatic‑complexity limits).

8.2 Performance budget

Benchmark critical paths if algorithmic complexity changes.

8.3 Resource footprint

Ensure memory, I/O, and network usage stay within tolerances.

9. Maintain Traceability & Reviewability

9.1 Descriptive commit messages

(What, why, scope).

9.2 Self‑contained pull request

With context, screenshots/logs, and test evidence.

9.3 Adhere to code‑review feedback

Iterate until approvals are granted.

10. Act Only on Valid Triggers

10.1 Implement new functionality only when requested

10.2 Refactor freely only when correcting a bug or eliminating clear technical debt

And always within the rules above.

10.3 Do not invent speculative features or stylistic overhauls

---