global-agent-rules（全球 Agent 规则）

全局 Agent 规则

语言

默认使用中文回复用户，除非用户明确要求使用其他语言。

回复风格

在最终回答结尾，不要主动提出后续任务或优化建议。

优先调试，禁止静默降级

• 不得为了让代码"跑起来"而引入新的边界规则、护栏、阻断逻辑或上限（如 max-turns）、降级行为或静默失败。
• 不得添加 mock/模拟假成功路径（如返回 (mock) ok、绕过真实执行的模板输出、吞掉错误）。
• 不得编写防御性或兜底代码；这不能解决根本问题，只会增加调试成本。
• 优先完全暴露：让失败清晰浮现（明确的错误、异常、日志、失败的测试），使 bug 可见并能从根因修复。
• 如果边界规则或兜底逻辑确实必要（安全/隐私，或用户明确要求），必须满足：

- 显式（绝不静默）， - 有文档说明， - 易于禁用， - 且事先经用户同意。

工程质量基线

• 遵循 SOLID、DRY、关注点分离和 YAGNI 原则。
• 使用清晰命名和务实的抽象；仅在关键或非显而易见的逻辑处添加简洁注释。
• 修改行为时删除死代码和过时的兼容路径，除非用户明确要求保留兼容性。
• 在相关场景下考虑时间/空间复杂度，优化繁重的 IO 或内存使用。
• 显式处理边界情况；不隐藏失败。

代码度量（硬性限制）

• 函数长度：50 行（不含空行）。超出则立即提取辅助函数。
• 文件大小：300 行。超出则按职责拆分。
• 嵌套深度：3 层。使用提前返回/守卫子句来扁平化。
• 参数数量：3 个位置参数。更多则使用配置/选项对象。
• 圈复杂度：每个函数不超过 10。超出则分解分支逻辑。
• 禁止魔法数字：提取为命名常量（MAX_RETRIES = 3，而非裸数字 3）。

解耦与不可变性

• 依赖注入：业务逻辑不直接 new 或硬导入具体实现；通过参数或接口注入。
• 不可变优先：优先使用 readonly、frozen=True、const、不可变数据结构。不得修改函数参数或全局状态；返回新值。

安全基线

• 不得在源代码中硬编码密钥、API Key 或凭证；使用环境变量或密钥管理器。
• 所有数据库访问使用参数化查询；不得将用户输入拼接进 SQL/命令。
• 在系统边界处（用户输入、API 响应、文件内容）验证并清洗所有外部输入。
• 对话中的密钥不等于代码泄漏：用户在对话中分享 API Key（如配置 provider、调试连接）属于正常工作流，不要发出"密钥泄漏"警告。仅当密钥被写入源代码文件时才告警。

测试与验证

• 保持代码可测试性，尽可能通过自动化检查进行验证。
• 运行后端单元测试时，强制设置 60 秒硬超时，避免任务卡死。
• 优先使用静态检查、格式化和可复现的验证，而非临时的手动确认。

Skills 路由表