文档图标 AI Coding 指引文档
▶ AI Native 最佳实践使用指引
概述
▶ 安装 CLI
Costrict CLI Claude Code CLI
▼ 安装插件
插件 for CoStrict CLI 插件 for Claude Code CLI
使用插件
▼ 云上 DevBox 使用指引
概述
▼ 快速上手
本地开发，上传镜像 轻量云上开发 云上Agent应用开发与发布
概述
了解 Agent Rules 的核心理念、架构设计和安装方式
一、什么是 Agent Rules?

Agent Rules 是一个智能的 AI 助手规则管理和部署工具，旨在连接内部知识与规则，推动agent开发稳定规范化，帮助开发团队统一管理、安装和部署 AI 助手规则，提升 AI 辅助开发的效率和质量。

v4.0 全面升级为插件驱动架构，支持 Claude Code 插件模式一键安装，自动激活 97+ Skills、63 条编码规范、6 大角色体系，无需手动配置即可获得完整的开发辅助能力。

二、核心价值
  • 统一管理 - 集中管理所有 AI 助手规则，避免规则分散和不一致
  • 插件驱动 - Claude Code 插件模式，SessionStart 自动激活，零配置即用
  • 智能适配 - 自动检测并适配多种 AI 工具，一次配置多处生效
  • 角色化安装 - 根据开发角色智能推荐规则，按需安装
  • 知识库集成 - 按产品分类的业务知识库，让 AI 更懂业务
三、提供给 AI 的能力

通过 install 命令，你可以为 AI 安装不同的角色，每个角色专注于特定的工作场景：

📋
AI需求分析师
安装命令：npx @sangfor/agent-rules install -m role -r ai_requirement_analyst --ai-tool claude
  • 核心能力：将任意格式的原始需求转化为结构化AI需求文档
  • 输出结构：Epic → Feature → Story 三级需求拆分
  • 适用场景：产品需求评审、需求文档编写、用户故事提炼
📊
系统需求分析师
安装命令：npx @sangfor/agent-rules install -m role -r requirement_analyst --ai-tool claude
  • 核心能力：将AI需求细化为系统需求，完成五级层级拆解
  • 输出结构：Epic → Feature → Story → Tech-系统级 → Tech-服务级
  • 适用场景：系统需求分析、接口定义、非功能性需求设计
🏛️
架构设计师
安装命令：npx @sangfor/agent-rules install -m role -r system_architect --ai-tool claude
  • 核心能力：系统架构设计、技术选型、设计模式应用
  • 输出内容：架构图、技术选型报告、架构决策记录(ADR)
  • 适用场景：新项目架构设计、系统重构、技术方案评审
🔧
设计到模块拆分助手
安装命令：npx @sangfor/agent-rules install -m role -r splitting_design_by_repo --ai-tool claude
  • 核心能力：基于设计文档，将改动需求拆分到指定代码仓库
  • 输出内容：各仓库的具体改动点、开发任务、依赖关系
  • 适用场景：多仓库项目的设计拆分、改动点分析、任务分配
📝
SPEC驱动开发工程师
安装命令：npx @sangfor/agent-rules install -m role -r spec_developer --ai-tool claude
  • 核心能力：将模糊需求转化为精确、可执行的技术规格文档
  • 输出内容：requirements.md、design.md、tasks.md
  • 适用场景：中小规模功能开发、SPEC驱动开发流程
🧪
API接口测试专家
安装命令：npx @sangfor/agent-rules install -m role -r api_test_expert --ai-tool claude
  • 核心能力：SCP/SCC平台API接口测试用例设计与执行
  • 测试维度：正常场景、异常场景、边界值、性能测试
  • 适用场景：API接口测试、自动化测试、接口质量保障
📚
产品知识库
安装命令：npx @sangfor/agent-rules install --kb-profile scp --ai-tool claude
  • SCP知识库：Cloudkitty计费、Ceilometer监控、Aodh告警等32个组件
  • SCC知识库：Phoenix框架、Medusa IAM、Datamapper等106个服务
  • SKYOPS知识库：云端代理、云梯、智能运维等9个服务
  • 适用场景：让AI理解产品架构和业务逻辑，生成更准确的代码
🔍
排障专家
安装命令：npx @sangfor/agent-rules install -m role -r bug_terminator --ai-tool claude
  • 核心能力：系统化排查和修复Bug，包含Investigator和fixer两个子角色
  • 排障流程：错误复现、根因分析、修复方案制定、验证修复
  • 适用场景：线上问题排查、复杂Bug修复、性能问题定位
四、七大原子信息类型

Agent Rules 基于七大原子信息类型构建，这是 AI 辅助开发的核心建设思路：

1
Skill（技能封装）

业界官方推荐下载命令的 skill 市场，封装可复用的开发技能

示例：功能开发工作流、PR 审查流程、代码架构设计
2
Rules（规范转化）

将企业规范转化为 AI 可执行的规则

示例：编码规范、API 设计规范、安全规范、测试规范
3
Checklist（质量清单）

自动化检查流程，确保代码质量

示例：代码审查清单、发布检查清单、安全检查清单
4
Template（模版标准化）

标准化输出格式，保证一致性

示例：需求文档模板、设计文档模板、API 文档模板
5
MCP（系统集成）

Model Context Protocol 集成，扩展 AI 能力

示例：数据库查询、API 调用、文件操作
6
Scripts（确定性脚本）

高可靠性操作脚本，自动化重复任务

示例：Git 工作流脚本、部署脚本、数据迁移脚本
五、官方推荐安装方式
推荐
插件模式安装（Claude Code 用户推荐）

插件模式是 Claude Code 用户的最佳选择。安装后 SessionStart 自动激活 97+ Skills，无需手动配置。

# 在 Claude Code 中执行以下两条命令
/plugin marketplace add http://mq.code.sangfor.org/20319/agent-rules.git
/plugin install spec-developer@agent-rules-marketplace

# 重启 Claude Code 即可自动激活
CLI
CLI 模式安装（其他 AI 工具或兼容模式）

CLI 模式安装方式，支持所有 AI 工具。提供交互式安装向导，支持角色、任务、预设等多种安装模式。

传统 CLI 安装方式，支持所有 AI 工具。提供交互式安装向导，支持角色、任务、预设等多种安装模式。

npx @sangfor/agent-rules install
安装与激活
了解如何安装和激活 Agent Rules
Costrict 安装激活 Claude Code 安装激活
0
确认仓库访问权限

执行以下命令验证是否具备 SSH 访问权限：

ssh -T git@mq.code.sangfor.org

若提示权限拒绝或连接失败，请联系 罗嘉欣65883 开通仓库访问权限后再继续。

1
添加 Agent Rules 到插件市场

在 Claude Code 中执行以下命令，将 Agent Rules 仓库注册到插件市场：

/plugin marketplace add http://mq.code.sangfor.org/20319/agent-rules.git
2
安装 spec-developer 插件

从已注册的市场中安装 spec-developer 插件：

/plugin install spec-developer@agent-rules-marketplace
3
重启 Claude Code

退出并重新打开 Claude Code，插件通过 SessionStart Hook 自动激活，注入所有 Skills 和规范。首次启动时会自动安装 kb-Product 产品知识库。

自动安装失败?

如果首次启动时 kb-Product 自动安装失败（网络问题等），可手动安装：

git clone git@mq.code.sangfor.org:CMP/AiCoding/kb-Product.git ~/.claude/skills/kb-kb-query
git clone git@mq.code.sangfor.org:CMP/AiCoding/kb-Product.git ~/.claude/skills/kb-kb-query
# 可选: 启用深度知识搜索
npm install -g @sangfor/knowledge-repos
Claude Code 安装激活

Claude Code 是一款智能代码助手，提供强大的代码补全、重构和分析功能。

更新
了解如何更新 Agent Rules 到最新版本

当 agent-rules 有新版本发布时，在 Claude Code 中执行 /plugin，进入 Marketplaces 标签页，选择 Update marketplace 即可拉取最新版本。

/plugin
Plugins Discover Installed Marketplaces Errors (1)
agent-rules-marketplace
git@mq.code.sangfor.org:CMP/AiCoding/agent-rules.git
1 available plugin
Installed plugins (1):
• spec-developer
AI 驱动的端到端开发工作流: 需求分析、系统需求、设计、编码、测试，支持复杂度自适应
Browse plugins (1)
> Update marketplace (last updated 2026/4/8)
Disable auto-update
Remove marketplace
Auto-update enabled. Claude Code will automatically update this marketplace and its installed
Enter to select. Esc to go back

在 /plugin → Marketplaces → Update marketplace 更新插件

/plugin
Plugins Discover Installed Marketplaces Errors (1)
agent-rules-marketplace
1 available plugin
Installed plugins (1):
• spec-developer
AI 驱动的端到端开发工作流: 需求分析、系统需求、设计、编码、测试，支持复杂度自适应
✓ Updated 1 marketplace
Browse plugins (1)
Update marketplace (last updated 2026/4/8)
> Disable auto-update
Remove marketplace
Auto-update enabled. Claude Code will automatically update this marketplace and its installed plugins.
Enter to select. Esc to go back

可在设置中开启 Auto-update 启用自动更新

自动更新已开启

Claude Code 会自动更新插件（页面底部提示 Auto-update enabled），也可手动触发确保获得最新 Skills 和规范。

本地开发，上传镜像
在本地完成开发后，将镜像上传至云端进行部署
上传镜像至 AgentBsae

在本地编码完成后，可通过自然语言上传至云上 AgentBase 的镜像仓库中，以便后续进行应用发布，如下图所示。在对话过程中需要进行连接及用户认证。

DevBox 上传代码流程
创建应用

指定单个容器镜像或 Helm Chart 创建高代码应用 ，完成外部访问、组件与服务等配置、在低代码平台中创建并发布 Agent 应用，将自动同步至 AgentBase。

创建应用流程 创建应用流程
Claude Code CLI 配置指引
了解如何配置 Claude Code CLI

Claude Code CLI 配置相关内容...

插件 for CoStrict CLI
了解如何在 CoStrict CLI 中使用插件
安装插件
1
添加 Agent Rules 到插件市场

在 Claude Code 中执行以下命令，将 Agent Rules 仓库注册到插件市场：

/plugin marketplace add http://mq.code.sangfor.org/20319/agent-rules.git
2
安装 spec-developer 插件

从已注册的市场中安装 spec-developer 插件：

/plugin install spec-developer@agent-rules-marketplace
3
重启 Claude Code

退出并重新打开 Claude Code，插件通过 SessionStart Hook 自动激活，注入所有 Skills 和规范。首次启动时会自动安装 kb-Product 产品知识库。

自动安装失败?

如果首次启动时 kb-Product 自动安装失败（网络问题等），可手动安装：

git clone git@mq.code.sangfor.org:CMP/AiCoding/kb-Product.git ~/.claude/skills/kb-query
# 可选: 启用深度知识搜索
npm install -g @sangfor/knowledge-repos
更新插件

当 agent-rules 有新版本发布时，在 Claude Code 中执行 /plugin，进入 Marketplaces 标签页，选择 Update marketplace 即可拉取最新版本。

/plugin
Plugins Discover Installed Marketplaces Errors (1)
agent-rules-marketplace
git@mq.code.sangfor.org:CMP/AiCoding/agent-rules.git
1 available plugin
Installed plugins (1):
• spec-developer
AI 驱动的端到端开发工作流: 需求分析、系统需求、设计、编码、测试，支持复杂度自适应
Browse plugins (1)
> Update marketplace (last updated 2026/4/8)
Disable auto-update
Remove marketplace
Auto-update enabled. Claude Code will automatically update this marketplace and its installed
Enter to select. Esc to go back

在 /plugin → Marketplaces → Update marketplace 更新插件

/plugin
Plugins Discover Installed Marketplaces Errors (1)
agent-rules-marketplace
1 available plugin
Installed plugins (1):
• spec-developer
AI 驱动的端到端开发工作流: 需求分析、系统需求、设计、编码、测试，支持复杂度自适应
✓ Updated 1 marketplace
Browse plugins (1)
Update marketplace (last updated 2026/4/8)
> Disable auto-update
Remove marketplace
Auto-update enabled. Claude Code will automatically update this marketplace and its installed plugins.
Enter to select. Esc to go back

可在设置中开启 Auto-update 启用自动更新

自动更新已开启

Claude Code 会自动更新插件（页面底部提示 Auto-update enabled），也可手动触发确保获得最新 Skills 和规范。

插件 for Claude Code CLI
了解如何在 Claude Code CLI 中使用插件
安装插件
1
添加 Agent Rules 到插件市场

在 Claude Code 中执行以下命令，将 Agent Rules 仓库注册到插件市场：

/plugin marketplace add http://mq.code.sangfor.org/20319/agent-rules.git
2
安装 spec-developer 插件

从已注册的市场中安装 spec-developer 插件：

/plugin install spec-developer@agent-rules-marketplace
3
重启 Claude Code

退出并重新打开 Claude Code，插件通过 SessionStart Hook 自动激活，注入所有 Skills 和规范。首次启动时会自动安装 kb-Product 产品知识库。

自动安装失败?

如果首次启动时 kb-Product 自动安装失败（网络问题等），可手动安装：

git clone git@mq.code.sangfor.org:CMP/AiCoding/kb-Product.git ~/.claude/skills/kb-query
# 可选: 启用深度知识搜索
npm install -g @sangfor/knowledge-repos
更新插件

当 agent-rules 有新版本发布时，在 Claude Code 中执行 /plugin，进入 Marketplaces 标签页，选择 Update marketplace 即可拉取最新版本。

/plugin
Plugins Discover Installed Marketplaces Errors (1)
agent-rules-marketplace
git@mq.code.sangfor.org:CMP/AiCoding/agent-rules.git
1 available plugin
Installed plugins (1):
• spec-developer
AI 驱动的端到端开发工作流: 需求分析、系统需求、设计、编码、测试，支持复杂度自适应
Browse plugins (1)
> Update marketplace (last updated 2026/4/8)
Disable auto-update
Remove marketplace
Auto-update enabled. Claude Code will automatically update this marketplace and its installed
Enter to select. Esc to go back

在 /plugin → Marketplaces → Update marketplace 更新插件

/plugin
Plugins Discover Installed Marketplaces Errors (1)
agent-rules-marketplace
1 available plugin
Installed plugins (1):
• spec-developer
AI 驱动的端到端开发工作流: 需求分析、系统需求、设计、编码、测试，支持复杂度自适应
✓ Updated 1 marketplace
Browse plugins (1)
Update marketplace (last updated 2026/4/8)
> Disable auto-update
Remove marketplace
Auto-update enabled. Claude Code will automatically update this marketplace and its installed plugins.
Enter to select. Esc to go back

可在设置中开启 Auto-update 启用自动更新

自动更新已开启

Claude Code 会自动更新插件（页面底部提示 Auto-update enabled），也可手动触发确保获得最新 Skills 和规范。

目录
  • 安装插件
  • 更新插件
概述
了解云上 DevBox 的核心内容
一、DevBox 简介

DevBox 是 AgentBase 平台提供的企业级云上轻量开发与运行沙箱环境，专为「代码不出库、轻量业务快速交付」设计。 它通过与本地 IDE 无缝打通，提供可一键拉起的标准化开发环境、按需配置的资源规格，同时集成容器镜像管理、发布验证、 运行监控能力，让开发者既能沿用本地编码习惯，又能在受控的企业云环境中完成开发、调试、测试与发布全流程， 核心解决传统本地开发的安全风险、环境不一致、运维成本高等问题。

🔒
代码不出库

企业级安全隔离，代码始终在受控环境中运行，杜绝源码泄露风险

⚡
一键拉起

标准化开发环境，秒级启动，无需手动配置依赖和工具链

🔄
无缝协同

与本地 IDE 深度集成，保持原有开发习惯，享受云端资源

二、核心价值
  • 1
    安全合规

    满足等保合规要求，代码与数据全程加密传输与存储

  • 2
    环境一致

    团队共享标准化环境，消除"在我机器上能跑"问题

  • 3
    弹性伸缩

    按需分配资源，从开发到测试无缝切换，成本可控

  • 4
    高效协作

    支持多人协同开发、环境共享、快速定位问题

三、DevBox 场景说明
1 场景一：本地开发后，云上发布验证/测试（主场景）
定位： 核心代码仍在本地研发，DevBox/AgentBase 仅承接测试、验收、Demo 演示、发布验证，不承担日常编码工作。
目标用户： 企业正式研发人员、测试人员、项目交付人员、售前人员；适用于有本地机房、核心代码严禁上云的传统企业、制造业、芯片、医疗等安全高要求客户。
使用流程：
  1. 1 开发者在本地环境完成编码，通过本地或CI流水线构建容器镜像/Helm Chart；
  2. 2 将制品上传至 AgentBase 私有镜像/制品仓库；
  3. 3 基于上传的镜像版本创建Agent应用，配置资源规格、网络、访问权限；
  4. 4 系统生成云上访问地址，测试/售前人员开展功能验证、演示、客户验收；
  5. 5 全程留存发布记录、资源占用、运行监控等日志，异常可快速回溯。
2 场景二：轻量低敏业务，纯云上DevBox开发（补充场景）
定位： 面向非核心、低风险业务，直接在云端 DevBox 完成全流程开发，主打快速搭建、即用即走、低运维成本。
目标用户： 前端开发、交互设计、新人培训、运维人员；适用场景为网页原型、内部小工具、脚本、数据分析、临时Demo等非核心项目。
使用流程：
  1. 1 开发者使用本地IDE的AI对话，输入自然语言指令创建DevBox，并完成账号鉴权；
  2. 2 选择Vue、Node.js等通用单模板，系统自动拉起对应云上开发环境；
  3. 3 本地IDE直连云端DevBox进行编码、调试，系统通过端口映射生成临时预览地址；
  4. 4 仅临时演示则直接使用预览地址，无需正式发布；如需长期运行，再启动标准发布流程。
3 场景三：AI Agent 应用专属开发与运行场景
定位： 适配 CrewAI、LangGraph 等AI智能体框架，DevBox 预装Agent运行环境，兼顾本地编码习惯与云端稳定运行，专门用于AI Agent类应用开发、调试、发布。
目标用户： AI Agent开发团队、智能运维、智能客服、自动化应用研发人员；聚焦AI原生应用团队。
使用流程：
  1. 1 开发者输入账号密码完成鉴权，通过自然语言指令创建DevBox，并自动匹配 CrewAI/LangGraph 专属环境模板与预设资源规则；
  2. 2 云端DevBox自动初始化Agent框架、依赖组件，建立本地IDE与云端环境的代码同步通道；
  3. 3 开发者沿用本地IDE编写代码，Agent程序在云端DevBox中运行、调试，获取临时访问入口验证功能；
  4. 4 功能验证完成后，将应用打包为镜像并发布至正式环境，同步展示版本号、资源实时消耗等信息。
CLI 使用指引 - Costrict CLI
了解如何使用 Costrict CLI 进行开发

Costrict CLI 开发使用相关内容...

轻量开发页面
轻量低敏业务，纯云上 DevBox 开发
轻量应用开发

通过自然语言在云上DevBox 中进行轻量应用开发，并根据对话返回的地址进行应用的预览，用户不需要登录 AgentBase 管理

轻量应用开发流程
使用插件
安装 spec-developer 插件并重启 Claude Code 后的使用方法

安装 spec-developer 插件并重启 Claude Code 后，无需任何额外配置或命令。在项目目录下打开 Claude Code，直接在对话框描述你的需求即可。

第一步：在项目目录启动 Claude Code
# 进入你的项目目录
cd /path/to/your/project

# 启动 Claude Code
claude

启动后 SessionStart Hook 自动激活所有 Skills，你会看到 using-spec-developer 的加载提示。

第二步：直接在对话框描述需求

无需任何 slash command，直接输入你的需求。AI 会自动识别复杂度并路由到合适的工作流。

小改动 / 简单需求

直接描述要做什么，AI 快速评估后直接进入实现：

> 给用户列表接口增加按创建时间排序的功能

Claude: 好的，我来分析当前代码结构...

Claude: 好的，我来分析当前代码结构...
> brainstorming → writing-plans → executing-plans
中大型需求 / 企业项目

描述需求背景，AI 先走需求分析 → 系统设计，每步完成后暂停等你审查确认再继续：

> 我们要为 SCC 的计费模块新增按量计费策略，支持多种资源类型

Claude: 这是一个企业级需求，我先查询产品知识库了解现有架构...

Claude: 这是一个企业级需求，我先查询产品知识库了解现有架构...
> kb-query → requirement-analysis
[生成 requirements.md, 请审查后回复"继续"]
> system-requirement-analysis
[生成系统需求文档，请审查后回复"继续"]
> design-spec → writing-plans → executing-plans
排障 / Bug 修复

描述问题现象或直接粘贴报错日志：

> 用户在并发创建资源时偶发 500 错误，日志如下:
[粘贴日志内容]

[粘贴日志内容]

Claude: 我来系统分析这个问题...
> systematic-debugging: SW1H → 收集证据 → 根因分析 → 修复方案
第三步：配合 AI 完成开发
Claude Code 操作技巧
  • @ 引用文件：输入 @文件路径 让 AI 直接读取指定文件，帮助 AI 快速定位上下文
  • 审查文档后回复"继续"：AI 在生成 requirements/design/tasks 后会暂停，检查无误后回复"继续"推进下一步
  • 审查文档后回复"继续"：AI 在生成 requirements/design/tasks 后会暂停，检查无误后回复"继续"推进下一步
  • 纠正 AI 直接说：发现 AI 理解有偏差，直接描述"这里不对，应该是..."，AI 会修正后继续
  • 中断后续接：会话中断后重新打开 Claude Code，输入"继续之前的任务"即可从断点恢复
  • Esc 打断：AI 执行过程中按 Esc 可随时打断，输入新指令修正方向
常见问题
  • 插件未激活？确保重启了 Claude Code，检查 .claude/settings.json 中是否有 spec-developer@agent-rules-marketplace 条目。
  • 知识库未自动安装？如网络问题导致失败，可手动执行： 
    git clone git@mq.code.sangfor.org:CMP/AiCoding/kb-Product.git ~/.claude/skills/kb-query
下一步
  • 项目开发实践 - 查看端到端开发完整案例
  • 项目开发实践 - 查看端到端开发完整案例
  • 知识库生成实践 - 为项目生成知识库，让 AI 更懂你的代码
  • 使用者模式 - 了解各 CLI 角色的使用方法
云上Agent应用开发与发布
了解 Agent 应用的开发场景和最佳实践
创建并发布Agent应用

通过自然语言创建并发布Agent应用，云上会自动创建DevBox，并配置发布所需的资源。

创建并发布Agent应用流程
前往AgentBase管理应用

可前往AgentBase进行Agent应用的运行、调试和发布验证及后续更全面的生命周期管理。

AgentBase管理界面
IDE 使用指引 - VS Code(Costrict)
了解如何在 VS Code 中使用 Costrict

VS Code Costrict 插件使用相关内容...

IDE 使用指引 - VS Code(Claude Code)
了解如何在 VS Code 中使用 Claude Code

VS Code Claude Code 插件使用相关内容...

目录
目录
目录
目录