# 把 AI 技能库当成代码来管理：工程团队落地指南

> 来源文章：[How to build a skills library for your engineering team](https://thenewstack.io/engineering-team-skills-library/)
>
> 适用对象：已经在团队内使用 Trae AI、Cursor、Claude Code、Codex、Copilot Agent 或其他 AI 编程助手的工程团队。

## 1. 为什么需要 AI 技能库

AI 编程助手真正难的，不是“接入哪个模型”，而是如何让团队的编码规范、架构经验、安全边界和 Review 习惯稳定进入 AI 的工作上下文。

如果每个工程师都在本地维护自己的 `.cursorrules`、Prompt 或 IDE 配置，时间一长就会出现问题：团队规则散落各处，没人知道哪些规则有效、哪些过期、哪些只是个人偏好。

更好的做法是：把 AI 技能库当成代码资产管理。

## 2. 什么是 AI 技能库

这里的“技能”可以理解为一组给 AI Agent 使用的 Markdown 规则文档。

它可以告诉 AI：

- 这个项目的代码风格是什么；
- 哪些安全行为禁止；
- 测试应该怎么写；
- 前端组件放在哪里；
- 后端业务逻辑应该放在哪一层；
- PR 描述应该包含什么；
- 哪些 API 不能随便调用；
- 遇到某类问题时应该按什么流程排查。

一句话：技能库就是团队给 AI 编程助手准备的工程操作手册。

它不是一次性的 Prompt，而是可以版本控制、评审、复用和持续更新的团队资产。

## 3. 个人本地配置为什么会失控

很多团队一开始会这样用 AI：

- 张三有自己的 `.cursor/rules`；
- 李四维护了一套 Claude Code 指令；
- 王五在项目 README 里写了一些 AI 注意事项；
- 安全团队单独发过一份禁止事项；
- 架构规范散落在 ADR、Wiki、飞书文档里。

短期能用，长期会失控。

### 3.1 标准不一致

同一个项目，不同工程师的 AI 助手可能遵循完全不同的规则。

一个人让 AI 写胖模型，另一个人让 AI 写薄模型；一个人要求补测试，另一个人没有测试约束。最后代码风格会越来越碎。

### 3.2 规则不可审计

本地 Prompt 文件通常没有统一历史记录。

你很难回答：

- 这条规则是谁加的？
- 为什么加？
- 现在还适用吗？
- 有没有人审过？
- 是否影响了所有人？

### 3.3 经验无法复用

Code Review 里反复出现的问题，通常只被修在当前 PR 里。

但如果不把它沉淀成 AI 技能，下次 AI 还是会犯同样的错。

### 3.4 规则会过期

架构变了、框架升级了、目录调整了，但个人 Prompt 不一定同步更新。

过期规则比没有规则更危险，因为它会稳定地产生错误建议。

## 4. 正确思路：Prompts as Code / Skills as Code

推荐把 AI 技能库像代码一样管理：

- 放进 Git 仓库；
- 用 PR 审查变更；
- 有维护人；
- 有更新时间；
- 有分组；
- 有强制规则和可选规则；
- 有同步脚本；
- 有健康度检查。

核心原则：不要让 AI 规则散落在个人机器上，要让它进入团队工程体系。

## 5. 推荐目录结构

可以从一个很简单的结构开始：

```text
ai-skills/
├── base/
│   ├── coding-style.md
│   ├── testing.md
│   ├── security-rules.md
│   └── pr-review.md
├── frontend/
│   ├── react-components.md
│   ├── web-vitals.md
│   └── accessibility.md
├── backend/
│   ├── api-design.md
│   ├── spring-boot-patterns.md
│   └── error-handling.md
├── devops/
│   ├── ci-cd.md
│   └── observability.md
└── meta/
    ├── how-to-create-new-skill.md
    └── repeated-feedback-to-skill.md
```

不用一开始就做复杂平台。先有目录、文件和 Git 历史，就已经比个人散落配置强很多。

## 6. 技能应该怎么分组

不要把所有规则塞进一个巨大文件。

推荐按使用场景分组。

### 6.1 基础技能：所有人都必须加载

适合放团队底线规则，例如：

- 安全红线；
- 禁止硬编码密钥；
- 测试要求；
- 错误处理规范；
- PR 描述模板；
- 通用代码风格。

示例：

```markdown
# 安全基础规则

- 禁止把 API Key、Token、密码写入代码。
- 所有外部服务凭据必须从环境变量读取。
- 不要在生产脚本中使用未确认的破坏性命令。
- 发现疑似密钥时，停止修改并提醒人工处理。
```

### 6.2 角色技能：按岗位加载

例如：

- 前端工程师加载 `frontend/`；
- 后端工程师加载 `backend/`；
- 平台工程师加载 `devops/`。

这样可以避免无关上下文污染 AI。

### 6.3 项目技能：按仓库加载

每个项目可以有自己的规则，例如：

```text
project-a/
└── AGENTS.md
```

或：

```text
project-a/
└── .cursor/rules/
```

项目技能应该描述：

- 项目结构；
- 常用命令；
- 测试方式；
- 禁止修改的关键路径；
- 本项目特有架构约束。

### 6.4 目录/文件范围技能：按路径触发

有些规则只应该在特定目录生效。

例如：

- `src/components/**/*.tsx` 才加载 React 组件规范；
- `src/main/java/**/*.java` 才加载 Spring Boot 优化规则；
- `infra/**` 才加载 Terraform/K8s 规则。

这样可以避免 AI 在无关文件里套用错误模式。

## 7. 强制技能和可选技能

技能库一定要区分两类规则。

### 7.1 强制技能

所有人、所有 AI Agent 都应该加载。

适合：

- 安全规则；
- 测试底线；
- 代码 Review 要求；
- 禁止事项；
- 生产环境保护规则。

示例：

```markdown
# 强制规则：外部 API 调用

- 新增外部 API 调用必须说明用途、超时、重试和错误处理。
- 禁止在未确认的情况下调用付费 API。
- 禁止把用户数据发送到未经批准的第三方服务。
```

### 7.2 可选技能

根据角色、项目、目录或任务加载。

适合：

- React 组件规范；
- Spring Boot 项目规范；
- Terraform 模块规范；
- 数据分析 Notebook 规范；
- 某个业务域的术语说明。

可选技能的关键是：不要让所有人加载全部规则。AI 上下文越多，不一定越好；无关规则越多，误导越多。

## 8. 技能文件应该怎么写

一个好的技能文件不应该只是“建议”，而应该告诉 AI：

- 什么时候使用；
- 应该怎么做；
- 不应该怎么做；
- 如何验证；
- 常见错误是什么。

推荐模板：

```markdown
# 技能名称

## 适用场景

当你修改 XXX 类型代码时使用本技能。

## 操作规则

1. 先阅读现有实现。
2. 保持当前项目风格。
3. 新增功能必须补测试。
4. 不要引入新依赖，除非人工确认。

## 禁止事项

- 禁止硬编码配置。
- 禁止跳过失败测试。
- 禁止修改 XXX 文件。

## 验证方式

修改完成后运行：

```bash
pytest tests/ -v
ruff check .
```

## 常见问题

- 如果测试依赖外部服务，使用 mock。
- 如果找不到项目入口，先阅读 README。
```

核心不是写得长，而是写得可执行、可验证、边界清楚。

## 9. 如何在 Trae AI 及主流 IDE 中落地与同步

目前工作流中，**Trae AI** 和 **Cursor** 对规则文件的支持最为原生且强大。

### 9.1 Trae AI 规则机制深度解析

在 Trae AI（基于 VS Code 的国产 AI 辅助编程工具）中，规则分为两个层次：

1. **个人规则 (User Rules)**：
   - **配置位置**：点击 AI 对话窗口右上角“设置”（齿轮） -> “规则”。
   - **保存路径**：全局配置文件中（通常不随项目代码库提交）。
   - **适用场景**：个人开发习惯与通用指令（例如：“代码编写优先使用函数式编程”、“所有注释请使用中文”）。
2. **项目规则 (Project Rules)**：
   - **保存路径**：项目根目录下的 **`.trae/rules/`** 文件夹。
   - **优先级**：**高于个人规则**。若两者发生冲突，优先遵循项目规则。
   - **适用场景**：团队代码规范、架构规范、禁止调用的接口、安全红线。
   - **核心优势**：可放入 Git 进行版本控制，确保全团队使用同一套 AI 规则标准。

### 9.2 最小可行方案：跨平台自动同步脚本

为了防止工程师本地的规则文件与集中管理的技能库仓库（例如 `ai-skills` 仓库）脱节，不要让大家手动复制。团队可以编写并约定使用一个健壮的同步脚本，将技能库中的特定模块一键同步到本地开发项目的规则目录下。

以下是一个适配 Trae AI 的高健壮性同步脚本示例（我们也可以同时支持 Cursor 目录）：

```bash
#!/usr/bin/env bash
# scripts/sync-trae-skills.sh
set -euo pipefail

# 1. 配置集中管理技能库的根路径与当前项目的规则目标路径
SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" &>/dev/null && pwd)
SKILLS_REPO="${SKILLS_REPO:-$(cd "$SCRIPT_DIR/.." &>/dev/null && pwd)}"
TARGET_DIR="$PWD/.trae/rules"
MANIFEST_FILE="$TARGET_DIR/.ai-skills-managed-files"
NEW_MANIFEST_FILE="$TARGET_DIR/.ai-skills-managed-files.tmp"

# 帮助信息
show_help() {
    echo "使用方式: $0 [选项]"
    echo "选项:"
    echo "  -s, --source DIR   指定集中技能库路径 (默认: $SKILLS_REPO)"
    echo "  -d, --dest DIR     指定目标项目根目录 (默认: $PWD)"
    echo "  -h, --help         显示帮助信息"
}

# 解析参数
while [[ $# -gt 0 ]]; do
    case $1 in
        -s|--source) SKILLS_REPO="$2"; shift 2 ;;
        -d|--dest) TARGET_DIR="$2/.trae/rules"; shift 2 ;;
        -h|--help) show_help; exit 0 ;;
        *) echo "未知参数: $1"; show_help; exit 1 ;;
    esac
done

# 2. 检查源技能库是否存在
if [ ! -d "$SKILLS_REPO" ]; then
    echo "❌ 错误: 找不到集中技能库目录 '$SKILLS_REPO'。"
    echo "请克隆技能库，或者通过 -s 参数指定其正确路径。"
    exit 1
fi

# 3. 准备目标规则目录
echo "⚙️ 正在同步 AI 技能到目标项目: $TARGET_DIR..."
mkdir -p "$TARGET_DIR"

# 4. 仅清理上次由同步脚本托管的规则，保留用户自定义 Markdown
rm -f "$NEW_MANIFEST_FILE"
touch "$NEW_MANIFEST_FILE"
if [ -f "$MANIFEST_FILE" ]; then
    while IFS= read -r managed_file; do
        if [[ -n "$managed_file" && "$managed_file" != */* && "$managed_file" == *.md ]]; then
            rm -f "$TARGET_DIR/$managed_file"
        fi
    done < "$MANIFEST_FILE"
fi

# 5. 根据项目类型选择性同步规则（例如，根据当前项目的语言环境）
# 同步基础规则（强制）
if [ -d "$SKILLS_REPO/base" ]; then
    for file in "$SKILLS_REPO/base/"*.md; do
        [ -e "$file" ] || continue
        cp "$file" "$TARGET_DIR/"
        basename "$file" >> "$NEW_MANIFEST_FILE"
    done
fi

# 智能探测并同步可选规则
if [ -f "package.json" ] && [ -d "$SKILLS_REPO/frontend" ]; then
    echo "📦 探测到前端项目，正在同步前端 AI 技能..."
    for file in "$SKILLS_REPO/frontend/"*.md; do
        [ -e "$file" ] || continue
        cp "$file" "$TARGET_DIR/"
        basename "$file" >> "$NEW_MANIFEST_FILE"
    done
fi

if [[ -f "pom.xml" || -f "build.gradle" || -f "build.gradle.kts" ]] && [ -d "$SKILLS_REPO/backend" ]; then
    echo "☕ 探测到 Java 后端项目，正在同步后端 AI 技能..."
    for file in "$SKILLS_REPO/backend/"*.md; do
        [ -e "$file" ] || continue
        cp "$file" "$TARGET_DIR/"
        basename "$file" >> "$NEW_MANIFEST_FILE"
    done
fi

if [[ -f "Dockerfile" || -f "docker-compose.yml" || -d ".github/workflows" || -d "k8s" ]] && [ -d "$SKILLS_REPO/devops" ]; then
    echo "🛠️ 探测到 DevOps/平台工程项目，正在同步运维 AI 技能..."
    for file in "$SKILLS_REPO/devops/"*.md; do
        [ -e "$file" ] || continue
        cp "$file" "$TARGET_DIR/"
        basename "$file" >> "$NEW_MANIFEST_FILE"
    done
fi

mv "$NEW_MANIFEST_FILE" "$MANIFEST_FILE"

echo "✅ AI 技能库同步成功！当前项目已激活专属 AI 规则。"
```

### 9.3 Windows 环境一键同步批处理工具 (免管理员权限)

如果您的团队成员大多在 Windows 环境下使用 Trae AI（基于 VS Code 的 Windows 客户端），并且由于公司内控原因**没有 Windows 管理员权限**，团队需要提供一个同样具备技术栈自动探测功能的免特权一键同步批处理文件（`.bat`）。

以下是专门为 Windows 开发者编写的 `scripts/sync-trae-skills.bat` 批处理脚本示例。它仅在当前用户的工作空间（`%CD%`）内执行只读和本地覆盖，完全避开了需要提权的敏感操作：

```cmd
@echo off
:: scripts/sync-trae-skills.bat
:: 启用延迟变量扩展并强制切换 CMD 窗口为 UTF-8 代码页，防止中文乱码，无需管理员权限
setlocal enabledelayedexpansion
chcp 65001 >nul

set "SOURCE_DIR=%~dp0.."
set "DEST_DIR=%CD%"

if not "%~1"=="" set "SOURCE_DIR=%~1"
if not "%~2"=="" set "DEST_DIR=%~2"

if not exist "%SOURCE_DIR%" (
    echo [x] 错误: 找不到指定的 AI 技能库源目录: "%SOURCE_DIR%"
    exit /b 1
)

set "TARGET_DIR=%DEST_DIR%\.trae\rules"
echo ====================================================
echo 🚀 开始为开发项目同步 Trae AI 专属技能库 (Windows)
echo 📂 技能源路径: %SOURCE_DIR%
echo 📂 目标项目路径: %DEST_DIR%
====================================================

if not exist "%TARGET_DIR%" mkdir "%TARGET_DIR%"
set "MANIFEST_FILE=%TARGET_DIR%\.ai-skills-managed-files"
set "NEW_MANIFEST_FILE=%TARGET_DIR%\.ai-skills-managed-files.tmp"
echo 🔄 正在清理旧托管规则文件...
if exist "%NEW_MANIFEST_FILE%" del /q /f "%NEW_MANIFEST_FILE%" 2>nul
type nul > "%NEW_MANIFEST_FILE%"
if exist "%MANIFEST_FILE%" (
    for /f "usebackq tokens=* delims=" %%m in ("%MANIFEST_FILE%") do (
        if not "%%m"=="" (
            if exist "%TARGET_DIR%\%%m" del /q /f "%TARGET_DIR%\%%m" 2>nul
        )
    )
)

set /a SYNC_COUNT=0

:: 智能探测并同步
if exist "%SOURCE_DIR%\base" (
    echo 👉 注入团队强制底线规则 (base)...
    for %%f in ("%SOURCE_DIR%\base\*.md") do (
        copy /y "%%f" "%TARGET_DIR%\" >nul
        echo %%~nxf>>"%NEW_MANIFEST_FILE%"
        echo   ✓ 已同步规则: %%~nxf
        set /a SYNC_COUNT+=1
    )
    
    :: 探测前端技术栈
    set "IS_FRONTEND=false"
    if exist "%DEST_DIR%\package.json" set "IS_FRONTEND=true"
    if exist "%DEST_DIR%\yarn.lock" set "IS_FRONTEND=true"
    if exist "%DEST_DIR%\pnpm-lock.yaml" set "IS_FRONTEND=true"

    if "!IS_FRONTEND!"=="true" (
        if exist "%SOURCE_DIR%\frontend" (
            echo 👉 探测到前端工程体系，注入前端专属规则 (frontend)...
            for %%f in ("%SOURCE_DIR%\frontend\*.md") do (
                copy /y "%%f" "%TARGET_DIR%\" >nul
                echo %%~nxf>>"%NEW_MANIFEST_FILE%"
                echo   ✓ 已同步规则: %%~nxf
                set /a SYNC_COUNT+=1
            )
        )
    )

    :: 探测 Java 后端技术栈
    set "IS_BACKEND=false"
    if exist "%DEST_DIR%\pom.xml" set "IS_BACKEND=true"
    if exist "%DEST_DIR%\build.gradle" set "IS_BACKEND=true"

    if "!IS_BACKEND!"=="true" (
        if exist "%SOURCE_DIR%\backend" (
            echo 👉 探测到 Java 后端工程体系，注入后端专属规则 (backend)...
            for %%f in ("%SOURCE_DIR%\backend\*.md") do (
                copy /y "%%f" "%TARGET_DIR%\" >nul
                echo %%~nxf>>"%NEW_MANIFEST_FILE%"
                echo   ✓ 已同步规则: %%~nxf
                set /a SYNC_COUNT+=1
            )
        )
    )

    :: 探测 DevOps / 平台工程技术栈
    set "IS_DEVOPS=false"
    if exist "%DEST_DIR%\Dockerfile" set "IS_DEVOPS=true"
    if exist "%DEST_DIR%\docker-compose.yml" set "IS_DEVOPS=true"
    if exist "%DEST_DIR%\.github\workflows" set "IS_DEVOPS=true"
    if exist "%DEST_DIR%\k8s" set "IS_DEVOPS=true"

    if "!IS_DEVOPS!"=="true" (
        if exist "%SOURCE_DIR%\devops" (
            echo 👉 探测到 DevOps/平台工程体系，注入运维专属规则 (devops)...
            for %%f in ("%SOURCE_DIR%\devops\*.md") do (
                copy /y "%%f" "%TARGET_DIR%\" >nul
                echo %%~nxf>>"%NEW_MANIFEST_FILE%"
                echo   ✓ 已同步规则: %%~nxf
                set /a SYNC_COUNT+=1
            )
        )
    )
) else (
    echo 👉 注入通用规则...
    for %%f in ("%SOURCE_DIR%\*.md") do (
        set "FILE_NAME=%%~nxf"
        if not "!FILE_NAME!"=="README.md" (
            copy /y "%%f" "%TARGET_DIR%\" >nul
            echo %%~nxf>>"%NEW_MANIFEST_FILE%"
            echo   ✓ 已同步规则: !FILE_NAME!
            set /a SYNC_COUNT+=1
        )
    )
)

move /y "%NEW_MANIFEST_FILE%" "%MANIFEST_FILE%" >nul

echo ====================================================
if !SYNC_COUNT! gtr 0 (
    echo 🎉 同步完成！共成功激活 !SYNC_COUNT! 个 AI 技能规则。
    echo 👉 提示: 请在 Trae AI 侧栏中确认规则生效情况。
) else (
    echo ⚠️ 同步结束，但未发现有效的规则文件。
)
echo ====================================================
endlocal
```

### 9.4 团队落地约定

团队可将同步脚本加入 Makefile、package.json 或本地自动化指令中，实现不同平台下工程师入职一键配置或在 CI/CD 中作为检查条件：

- **Windows 用户直接双击或运行**：
  直接在本地项目根目录运行（无需管理员权限）：
  ```cmd
  scripts\sync-trae-skills.bat
  ```
- **macOS/Linux 用户通过 Shell 执行**：
  ```bash
  bash scripts/sync-trae-skills.sh
  ```
- **通过 Makefile 兼容多平台**：
  ```makefile
  sync-skills:
  ifeq ($(OS),Windows_NT)
  	@cmd /c scripts\sync-trae-skills.bat
  else
  	@bash scripts/sync-trae-skills.sh
  endif
  ```
- **对于前端项目，通过 package.json 智能绑定**：
  ```json
  "scripts": {
    "prepare": "node -e \"const os = require('os'); const { execSync } = require('child_process'); if (os.platform() === 'win32') { execSync('scripts\\\\sync-trae-skills.bat', { stdio: 'inherit' }); } else { execSync('bash scripts/sync-trae-skills.sh', { stdio: 'inherit' }); }\""
  }
  ```

这种双平台、无特权依赖的一键同步设计，能彻底扫清团队落地时的客户端环境障碍，确保全员以零摩擦接入一致的 AI 工程上下文。

## 10. 技能从哪里来

不要凭空写一堆规范。最好的技能来自真实工程摩擦。

### 10.1 高频 Code Review 评论

如果 Review 里反复出现类似评论：

- “这里应该补测试”；
- “这个错误不能直接吞掉”；
- “这个逻辑不应该写在 Controller”；
- “这里不能直接调用外部 API”；
- “这个组件不应该访问全局状态”。

就应该把它沉淀成技能。

原则：同一个问题出现三次，就不要只改代码，要补规则。

### 10.2 架构决策记录 ADR

ADR 里通常有重要背景：

- 为什么选择某个方案；
- 为什么不选另一个方案；
- 哪些边界不能破坏。

这些很适合转成 AI 可读规则。

### 10.3 事故复盘

事故复盘里经常有“以后不要再这样做”。

这些内容应该进入技能库，尤其是：

- 配置错误；
- 权限错误；
- 数据库迁移风险；
- 灰度发布问题；
- 缓存一致性问题。

### 10.4 入职文档

新人需要知道的内容，AI 也需要知道。

例如：

- 项目怎么启动；
- 哪些目录是核心；
- 哪些文件不能随便动；
- 如何跑测试；
- 如何提交 PR。

### 10.5 开发者反复纠正 AI 的内容

如果一个工程师在同一类任务中反复告诉 AI：

- “不要这样写”；
- “我们项目不是这个风格”；
- “这里应该用已有工具”；
- “这个命令不对”。

这就是新技能的候选来源。

## 11. 建立反馈闭环

技能库不是一次性文档，而是一个持续迭代系统。

可以建立这样一个流程：

1. AI 生成代码；
2. 人类 Review 发现结构性问题；
3. 判断是否是重复问题；
4. 如果是，新增或修改技能；
5. 技能走 PR 审查；
6. 合并后同步到团队环境；
7. 后续 AI 自动遵循新规则。

这个闭环的价值是：不只是修复这一次代码，而是降低未来同类错误出现的概率。

## 12. 技能库需要健康度管理

技能也会腐烂。

建议给每个技能至少记录：

- 维护人；
- 创建时间；
- 最近更新时间；
- 适用项目/目录；
- 是否强制；
- 是否已废弃；
- 验证方式。

可以用简单的 frontmatter：

```markdown
---
name: backend-error-handling
owner: backend-platform
scope: backend/**/*.py
required: true
updated: 2026-05-14
---

# 后端错误处理规则
```

定期检查：

- 超过 90 天未更新的技能；
- 没有维护人的技能；
- 和当前项目结构不匹配的技能；
- 被多人反馈无效的技能；
- 内容过长、过泛、不可执行的技能。

## 13. 一周内的最小落地方案

如果你不想一开始做平台，可以按这个顺序落地。

### 第一天：建仓库和基础目录

```text
ai-skills/
├── base/
├── frontend/
├── backend/
└── meta/
```

先不要追求完整，能跑起来最重要。

### 第二天：沉淀 3 条强制基础技能

建议先写：

- 安全规则；
- 测试规则；
- PR 规则。

### 第三天：为一个项目接入

在项目里加入同步脚本：

```bash
bash scripts/sync-trae-skills.sh
```

把基础技能同步到项目根目录的 `.trae/rules/` 目录中。

### 第四天：从最近 10 个 PR 提炼规则

找出重复 Review 评论，转成 3-5 条技能。

### 第五天：建立 PR 审查流程

所有技能变更必须走 PR。

Review 重点看：

- 是否太泛；
- 是否可执行；
- 是否有适用范围；
- 是否有验证方式；
- 是否会误导其他项目。

### 第六天：加健康度字段

给技能加 owner、scope、updated、required 等元数据。

### 第七天：复盘效果

观察：

- AI 是否少犯同类错误；
- 工程师是否愿意同步；
- 哪些规则太长或无效；
- 哪些技能应该拆分。

## 14. 一个可直接参考的技能示例

```markdown
---
name: backend-api-error-handling
owner: backend-platform
scope: backend/**/*.py
required: true
updated: 2026-05-14
---

# 后端 API 错误处理规则

## 适用场景

当你修改后端 API、服务层或外部服务调用代码时，必须使用本规则。

## 规则

1. 外部调用必须设置超时。
2. 外部调用失败时必须记录上下文日志。
3. 不要裸 `except Exception` 后直接吞掉错误。
4. 面向用户的错误信息不能暴露内部实现细节。
5. 新增错误分支必须补测试。

## 禁止事项

- 禁止硬编码 Token、密码、内部 IP。
- 禁止在业务代码中直接打印异常。
- 禁止为了让测试通过而删除断言。

## 验证方式

运行：

```bash
pytest tests/ -v
ruff check .
```

## 常见错误

错误示例：

```python
try:
    client.call()
except Exception:
    pass
```

正确方向：

```python
try:
    client.call(timeout=5)
except ClientError as exc:
    logger.warning("external client call failed", exc_info=exc)
    raise ServiceUnavailable("external dependency failed") from exc
```
```

## 15. 常见误区

### 15.1 把技能写成大而全的百科

技能不是文档库。AI 需要的是当前任务可执行的约束，不是长篇背景材料。

### 15.2 所有规则都强制加载

强制规则太多，会让 AI 上下文膨胀，也会增加误触发。

强制规则只放底线：安全、测试、生产风险、代码基础规范。

### 15.3 只写“应该”，不写“验证”

例如：

```markdown
应该写高质量代码。
```

这没有意义。

更好的写法是：

```markdown
新增业务逻辑必须补测试，并运行 pytest tests/ -v。
```

### 15.4 技能没有维护人

没人负责的技能迟早过期。过期技能会稳定地产生错误建议。

### 15.5 只在本地改，不进 Git

本地规则无法共享、无法审查、无法回滚。技能库的核心价值就是团队级治理。

## 16. 推荐结论

如果你的团队已经在用 Trae AI、Cursor、Claude Code、Codex、Copilot Agent 或其他 AI 编程助手，那么下一步不应该只是换模型，而是建立团队级 AI 技能库。

最小可行方案：

1. 把 AI 规则写成 Markdown；
2. 放进 Git；
3. 区分强制和可选；
4. 写同步脚本；
5. 从 Code Review 和事故复盘中持续补规则；
6. 定期清理过期技能。

一句话总结：AI 技能库的本质，是把团队的工程经验、边界和反复纠正过的问题，变成 AI Agent 可以稳定读取和执行的代码化资产。