---
name: global-agent-rules
description: 全局 Agent 规则，包含语言、回复风格、调试优先级、工程质量基线、代码度量硬性限制、安全基线、测试验证标准和 Skills 路由表。适用于所有编程任务。
user-invocable: false
---

# 全局 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 路由表

| 场景 | Skill | 触发词 |
|------|-------|--------|
| 网络调研 / 文档查询 / 事实核查 | `researcher` | "search"、"research"、"搜索"、"调研"、"查文档"、"查一下"、"帮我搜" |
| 代码探索 / 架构分析 | `explore` | "在哪 / 怎么 / 调用链 / 数据流" |
| 多步骤任务追踪（轻量：3-8 步） | `taskmaster` | 使用 CSV 追踪的快速多步骤任务 |