# TypeScript 智能体规则集

本规则集定义 AI/自动化智能体在处理 TypeScript/JavaScript 代码时必须遵守的核心约束。

## 范围与优先级

- 作为仓库级基线规则集使用；更靠近代码目录的规则更具体并可覆盖基线。
- 当智能体规则与 docs 冲突：安全/合规优先，其次保持仓库一致性。

## 智能体工作原则（铁律）

1. 先理解目标与上下文，再动手改代码
2. 修改要小而清晰；避免无关重构
3. 发现安全问题（明文密钥/鉴权漏洞）立即标注或修复
4. 不引入新依赖或工具，除非明确要求

## TypeScript/JavaScript 核心约定（不可违反）

- 语言标准：业务代码优先 TypeScript（`.ts/.tsx`）；JavaScript（`.js/.mjs/.cjs`）仅用于脚本、配置或兼容场景
- 类型：禁止使用 `any`；优先 `unknown`；所有公共 API 必须有明确类型注解
- 代码风格：以仓库既有 ESLint/Prettier 配置为准；未经沟通不切换 formatter/linter
- Import：使用 ES Module（`import`/`export`）；避免 `require()`；按 外部 → 内部 → 相对路径 分组
- 命名：文件 `kebab-case.ts/.js`；类/接口/类型 `PascalCase`；函数/变量 `camelCase`；常量 `UPPER_WITH_UNDER`；私有成员 `_camelCase`
- 异步：优先 `async/await`；避免裸 `.then()` 链；错误必须处理
- JavaScript 质量底线：必须通过 ESLint；推荐启用 `@ts-check` + JSDoc 做静态检查

## 权威来源

- 代码风格：`docs/typescript/code_style.md`
- 命名规范：`docs/typescript/naming.md`
- 工具链：`docs/typescript/toolchain.md`
- 配置清单：`docs/typescript/configuration.md`

## Skills（按需加载）

- `$commit-message`

## 与开发规范的关系

- 规范文档：`docs/typescript/` 与 `docs/common/`
