CloudBase-AI-Toolkit AGENTS.md

# 需求文档

## 介绍

需求描述

## 需求

### 需求 1 - 需求名称

**用户故事：** 用户故事内容

#### 验收标准

1. 采用 ERAS 描述的子句 While <可选前置条件>, when <可选触发器>, the <系统名称> shall <系统响应>，例如 When 选择"静音"时，笔记本电脑应当抑制所有音频输出。
2. ...
...

1. 技术方案设计：对于需要 spec 的需求，在完成需求设计之后，你会根据当前的技术架构和前面确认好的需求，进行技术方案设计，保存在 specs/spec_name/design.md 中，精简但是能够准确描述技术架构（例如架构、技术栈、技术选型、数据库/接口设计、测试策略、安全性），必要时可以用 mermaid 来绘图，跟我确认清楚后，才进入下阶段。对于不需要 spec 的小需求，可以直接在对话中给出精简方案并继续执行。

2. 任务拆分：对于需要 spec 的需求，在完成技术方案设计后，你会根据需求文档和技术方案，细化具体要做的事情，保存在 specs/spec_name/tasks.md 中，跟我确认清楚后，才开始正式执行任务，同时更新任务状态。对于不需要 spec 的小需求，可以直接给出精简任务说明或直接执行。

   注：specs/ 已加入 .gitignore，spec 文档只写在本地、不要 git add 到公开仓库（含内部信息，完整历史归档在私有仓库 cloudbase-mcp-specs-archive）。

格式如下

# 实施计划

- [ ] 1. 任务信息
  - 具体要做的事情
  - ...
  - _需求: 相关的需求点的编号

<project_rules>

1. 项目结构

   • doc 存放对外的文档
   • mcp 核心的 mcp package
   • config 用来给 AI IDE 提供的规则和 mcp 预设配置
   • tests 自动化测试
   • skills 项目级 skills 源目录
   • specs 需求/设计/任务文档（本地目录，不提交到公开仓库。含内部信息，仅保留 plugin-marketplace-listing/ 与 npm-supply-chain-security-hardening/ 两个被代码或规范依赖的子目录；完整历史归档在私有仓库 cloudbase-mcp-specs-archive）

2. AGENTS 文件约定

   • AGENTS.md 为项目及子目录的唯一可信源
   • CLAUDE.md、CODEBUDDY.md 均为指向 AGENTS.md 的软链
   • 新增子目录时，只需创建 AGENTS.md，用软链补齐 CLAUDE.md

3. Skills & Rules 目录约定

   • .agents/skills 为 skills 的唯一可信源，.codebuddy/skills、.claude/skills 软链至此
   • .agents/rules 为 rules 的唯一可信源（尚未创建时以 .agents/rules 为目标）
   • 新增 skills 请直接添加到 skills/ 目录，.agents/skills/ 下的软链会自动关联
   • 如果使用 npx skills 命令添加 skills 时保留 Universal 选项，不用重复添加 claude 和 codebuddy 选项
   • 某个目录中只要有 AGENTS.md、CLAUDE.md 和 .agents/skills、.claude/skills 中的任意一个，就需要自动补齐

4. 项目子目录规则

   • mcp/ 子目录同样适用本约定：mcp/AGENTS.md 为源，mcp/CLAUDE.md、mcp/CODEBUDDY.md 为软链 </project_rules>

<internal_dirs>

本地内部目录的存放、同步与获取

两个目录都不提交到公开仓库，只在本地维护并归档到私有仓：

目录	内容	为什么不入库
specs/	规格 / 设计 / 审视报告	含内部任务 ID、审视报告、评测/归因上下文
.workbuddy/	IDE 本地状态：AI 每日记忆、plans、expert 会话历史	类比 .idea/ / .vscode/，本就不该进版本控制；记忆里带内部任务 ID 与未公开决策

specs/ 里仅 specs/plugin-marketplace-listing/ 与 specs/npm-supply-chain-security-hardening/ 两个被代码或规范依赖的子目录留在仓库里，其余全部忽略。.workbuddy/ 全量忽略。

写：新 spec 照旧写在本仓库 specs/<name>/{requirements,design,tasks}.md，只是不要 git add。.workbuddy/ 由 IDE 自行维护，不用管。