编程指导规范 (CODE GUIDELINES)
- 清晰优先于技巧（Clarity over cleverness）: 始终优先选择简单的解决方案。
- 一致性优先于个性（Consistency across layers）
- 不可变与可预测（Immutable and predictable behavior）
- 编排优先于实现（Orchestration over Implementation）: 高层逻辑应作为流程的协调者，而非细节的执行者。
- 质量与深度： 优先确保高质量设计、可靠实现与丰富功能。构建真正可用的完整应用，而不是演示性质的应用。
- [MUST] 已存在的代码若不符合代码规范，则忽略，只对新编写的代码负责。
- [MUST] 所有注释使用英文。类、方法、函数注释首句使用第三人称动词开头: 示例
Creates a new user record.，行内注释使用动词开头: Create temporary file - [SHOULD] 采用编排式代码风格 (Orchestrator Pattern): 高层函数应仅描述“做什么” (What) 而非“怎么做” (How)。主流程函数应由一系列语义清晰的子函数调用组成，将具体循环、解析等实现细节下沉到独立函数中。
- [SHOULD] **单一职责原则（Single Responsibility Principle）：**当一个文件包含多个逻辑关注点或超过 300 行时，主动建议拆分为子模块或 Hooks。
- [MUST] 私有函数应放置在公有函数下方。
- [SHOULD] 保持代码库干净整洁、结构清晰。
- [MUST] 严禁使用 'any' 类型 (Strict Typing): 在 TypeScript/Python 等动态语言中，禁止显式或隐式使用
any。必须定义具体类型、Interface，或使用 unknown 配合类型守卫 (Type Guards) 进行收窄。 - [MUST] Input Validation: 所有外部输入（API 参数、表单数据）必须使用 Zod/Pydantic 进行运行时验证。
- [MUST] SQL Injection: 必须使用参数化查询或 ORM 方法，严禁拼接 SQL 字符串。
- [MUST] 常量使用大写和下划线,如
UPPER_SNAKE_CASE
- [SHOULD] 数据驱动设计（Data-Driven Design）: 能获取的数据才是设计数据结构的基础.
- [MUST] 尽可能避免代码重复，这意味着需要检查代码库中是否已有类似的代码或功能。
- [MUST] DRY 原则,优先复用现有组件和工具函数，避免重复造轮子。
- [MUST] 修复问题或 bug 时，不要在现有实现之外引入新的模式或技术，除非已完全用尽现有方案。如果最终确实需要新的实现，必须移除旧的实现，避免重复逻辑。
- [SHOULD] 编写代码时要考虑不同的环境：开发（dev）、测试（test）和生产（prod）。
- [SHOULD] 优先在顶层或边界层统一处理错误（Global Error Handling），避免在业务逻辑层到处散落 try-catch。
- [SHOULD] 尽量避免在文件中编写脚本，尤其是在脚本只会运行一次的情况下。
- [SHOULD] 避免全局变量
- [MUST] 优先使用项目已有的技术栈和库,新引入依赖需要说明必要性和替代方案对比
- [MUST] 仅在测试环境中使用 mock 数据，绝不在开发或生产环境中 mock 数据。
- [MUST] 禁止在影响开发或生产环境的代码中加入 stub 或 fake 数据的模式。
- [MUST] 单元测试禁止写注释。
- [SHOULD] 单元测试命名格式为
methodName_testScenario：extractUuid_validUrlWithQueryParams。
- [MUST] 只对明确被要求的内容进行修改，或在完全理解且与请求直接相关的情况下才进行额外修改。
- [MUST] 在覆盖 .env 文件等配置文件前必须先询问并确认，禁止未经确认就覆盖。
- [MUST] 在编写复杂逻辑代码前，先说明设计思路,技术选型理由,函数调用链。
- [MUST] 遇到不确定的需求时，主动澄清而非猜测实现。
- [SHOULD] 新引入依赖需要说明必要性和替代方案对比。
- Analyze: 仔细阅读现有代码库 (Codebase)，理解上下文。
- Think: 在输出代码前，先在对话中简述你的改动计划。
- Implement: 编写代码，确保符合所有 [MUST] 规则。
- Review: 再次检查代码是否引入了新的 Bug，是否破坏了现有的类型定义。
