在项目中为 AI 代理设置框架

高性能AI代理的项目结构指南

AI代理依赖清晰、一致的项目结构才能高效运行。建立标准化的开发框架，能让代理理解系统架构、执行测试并自主与环境交互，无需频繁人工干预。这些原则适用于Claude Code、Cursor等各类开发工具。

核心规则配置

在项目根目录创建一个文件——CLAUDE.md（或对应代理的等效文件），明确列出目录结构、关键命令和通用开发规范。避免提供具体实现细节：代码本身即为最佳文档。

示例基础文件：

## 结构
├── src/           — 服务代码
├── tests/         — 测试套件
├── migrations/    — Alembic数据库迁移文件
└── notebooks/     — 临时脚本

## 命令
- 运行测试：`pytest tests/ -x`
- 代码检查：`ruff check . --fix`
- 数据库升级：`alembic upgrade head`
- 启动服务：`docker compose up`

此配置可彻底消除重复解释架构与常规操作的困扰。通过脚本强制执行编码规范，而非依赖手册。

当代理出现错误时，应分析上下文。若出现方法重复或类位置错误，应补充模块化规则文件。

something-cool/
├── CLAUDE.md                          # 通用规则
├── src/
│   ├── auth/
│   │   ├── CLAUDE.md                  # SSO规则
│   │   └── ...
│   ├── billing/
│   │   ├── CLAUDE.md                  # 基于合同的变更规则
│   │   └── ...

设置不完整的表现：

• 代理需手动查找模块。
• 在依赖关系或注册逻辑上犯基础错误。

通过技能集成运行环境

AI代理不仅处理代码，还需与日志、指标和数据库交互。使用技能机制整合外部服务：定义函数并提供可执行脚本。

技能目录结构：

└── skills/
    ├── logs/
    │   ├── SKILL.md
    │   └── search_logs.py
    ├── metrics/
    │   ├── SKILL.md
    │   └── query_grafana.py
    ├── database/
    │   ├── SKILL.md

日志技能的SKILL.md示例：

---
name: logs
description: 搜索并分析应用日志
allowed-tools: Bash, Read
---

使用以下脚本搜索日志：
python .claude/skills/logs/search_logs.py --query "error" --since "1h"
python .claude/skills/logs/search_logs.py --trace-id "abc123"

现在，代理可独立获取洞察并排查问题。

跨仓库与团队协作兼容性

通过公共市场或内部平台共享技能，降低团队成员接入门槛。

为统一团队内多个代理的行为，推荐使用rulesync——CLI工具，从单一源生成25+工具所需的指令文件。

Rulesync结构：

.rulesync/rules/
├── overview.md          # root: true
├── auth.md              # globs: ["src/auth/**"]
└── billing.md           # globs: ["src/billing/**"]

带前置元数据的Markdown文件：

---
root: false
globs: ["src/auth/**"]
targets: "*"
description: SSO集成规则
---
规则内容在此处

生成命令：

• rulesync generate --targets "claudecode"
• rulesync generate --targets "cursor"
• rulesync generate --targets "copilot"

结果：自动生成CLAUDE.md、.cursorrules、copilot-instructions.md，并准确放置到目标路径。

后台代理用于持续监督

部署后台代理，自动监控代码风格、结构合理性及无用代码：

claude -p "检查代码风格：命名规范、结构合理性、死代码" \
  --allowedTools "Read,Grep,Glob"

实现自动化代码审查。

关键要点

• 模块化规则：在子目录中放置CLAUDE.md，提升上下文清晰度。
• 环境技能：结合脚本与说明，支持日志、指标、数据库访问。
• Rulesync：单源驱动多代理一致性。
• 持续演进：随错误出现不断扩展规则。
• 极简主义：仅关注结构与命令，不包含实现细节。

— Editorial Team