✨ 核心功能#
📁 目录结构与 AI 契约#
AGENTS.md：AI 的最高宪法与导航路由。任何 AI 进入本项目，都会首先读取此文件，了解全局规则并找到所需具体规范的路径。.agents/：AI 智能体专属配置与知识库。详见下方 .agents 目录详解 章节。
🤖 .agents 目录详解#
.agents/ 是本项目 AI 智能体协作体系的核心载体，作为 AGENTS.md（全局路由）的具体实现落地层。它通过模块化的领域知识库和标准化工具集，解决 AI 开发中常见的"上下文污染"和"规则遗忘"问题。与其对应，项目根目录的 docs/ 面向人类开发者，而 .agents/ 则专门为 AI 智能体设计。
定位与核心作用#
维度 |
说明 |
|---|---|
定位 |
AI 智能体的领域知识库、工具箱与执行契约的物理存储层 |
核心作用 |
① 提供按需读取的领域规范，降低 Token 消耗；② 统一管理技能（Skills）的标准化定义与执行；③ 沉淀 AI 专属的分析产物与知识图谱 |
设计原则 |
模块化、按需加载、人机隔离 —— AI 读取 |
文件层级规范#
.agents/
├── README.md # 本目录的总览与使用说明
├── rules/ # 领域开发规范（按技术栈/职能拆分）
│ ├── frontend.md # 前端开发规范
│ ├── backend.md # 后端开发规范
│ └── skills.md # 技能（Skill）开发规范
├── workflows/ # 特定工作流的 AI 执行指南
│ └── pr-review.md # PR 代码审查清单
├── templates/ # 标准化模板文件（供开发者与 AI 复用）
│ └── SKILL.md # 技能描述文件官方模板
├── scripts/ # 供智能体调用的自动化校验或执行脚本
├── docs/ # AI 专属文档存储区（与人类 docs/ 隔离）
│ ├── README.md # AI 专属文档区说明
│ └── superpowers/ # 技能（Superpower）的规格与回顾归档
│ ├── specs/ # 技能设计规格文档
│ └── retrospectives/ # 技能开发回顾与复盘
├── skills/ # 已安装的可复用技能包
│ ├── skill-creator/ # 技能创建器
│ │ ├── SKILL.md # 技能定义文件（必填）
│ │ ├── agents/ # 技能专属子智能体定义
│ │ ├── scripts/ # 技能运行脚本
│ │ ├── references/ # 技能参考文档
│ │ ├── assets/ # 技能静态资源
│ │ ├── eval-viewer/ # 评估结果查看器
│ │ └── tests/ # 技能测试用例
│ └── task-execution-summary/ # 任务执行总结技能
│ ├── SKILL.md # 技能定义文件（必填）
│ ├── references/ # 参考文档（API、错误码、模板等）
│ └── evals/ # 技能触发评估数据
└── ...
存储的核心资源类型#
资源类型 |
存放位置 |
内容说明 |
|---|---|---|
开发规范 |
|
前端、后端、技能开发等领域的具体技术栈规范与编码约束 |
工作流定义 |
|
PR Review 等标准化工作流的 AI 执行检查清单 |
模板文件 |
|
供开发者与 AI 复用的标准化模板（如 |
自动化脚本 |
|
供 AI 智能体调用的校验、构建、评估等自动化工具 |
AI 专属文档 |
|
架构分析、设计规格（Spec）、开发回顾等仅面向 AI 的知识产物 |
可复用技能 |
|
遵循 Agent Skills 官方规范的独立技能包，每个技能包含 |
与项目其他核心目录的联动关系#
┌──────────────────────────┐
│ AGENTS.md │
│ (AI 全局路由与宪法) │
└────────────┬─────────────┘
│ 导航分发
┌─────────────────┼─────────────────┐
▼ ▼ ▼
┌──────────────────┐ ┌──────────────┐ ┌──────────────┐
│ .agents/rules/ │ │ .agents/ │ │ .agents/ │
│ (领域规范) │ │ workflows/ │ │ skills/ │
└────────┬─────────┘ │ (工作流) │ │ (技能包) │
│ └──────┬───────┘ └──────┬───────┘
│ │ │
▼ ▼ ▼
┌──────────────────────────────────────────────────────┐
│ 实际项目源代码 (src/ 或项目根) │
└──────────────────────────────────────────────────────┘
┌──────────────────┐ ┌──────────────────┐
│ .agents/docs/ │ ◄─隔离─► │ docs/ │
│ (AI 专属文档) │ │ (人类开发者文档) │
└──────────────────┘ └──────────────────┘
AGENTS.md→.agents/：全局路由指向具体规范文件，AI 按任务类型按需读取.agents/rules/下的对应规范。.agents/rules/→ 项目源代码：规则中定义的技术栈、编码约束直接约束 AI 对源代码的生成与修改行为。.agents/skills/↔.agents/templates/：技能定义文件（SKILL.md）基于模板创建，确保标准化。.agents/docs/↔docs/：物理隔离。AI 的分析产物、设计规格放入.agents/docs/，面向人类的说明文档放入docs/。遵循"双向同步"原则：当.agents/发生结构性变更时，需同步更新docs/中的对应说明。
权限配置要求#
操作 |
权限要求 |
说明 |
|---|---|---|
读取 |
项目所有成员 |
AI 智能体与开发者均可自由读取规范与模板 |
新增/修改 rules/ |
需 PR 审查 |
由核心维护者（架构师/AI Engineer）审核，防止规则冲突或上下文污染 |
新增技能 (skills/) |
需 PR 审查 |
必须包含合规的 |
修改 templates/ |
需 PR 审查 |
模板变更影响所有基于其创建的技能，需评估兼容性 |
写入 .agents/docs/ |
AI 智能体可自由写入 |
AI 在执行过程中可沉淀分析产物，人类开发者通常无需直接操作 |
删除废弃规则 |
需 PR 审查 |
需同步更新 |
维护责任与更新频率#
维度 |
详情 |
|---|---|
维护责任人 |
项目架构师 或 指定的 AI 协作负责人（AI Engineer），统一维护以避免多人修改导致 AI 行为逻辑冲突 |
更新频率 |
① 每次项目架构大版本发布或引入新核心依赖时，必须更新对应规范；② 每个开发迭代（Sprint）结束时，对 |
过期规则清理 |
废弃的规则应及时从 |
变更审计 |
所有对 |