Skip to content

Commit f30b546

Browse files
CarlJiCarlJi
committed
doc(codeagent): support custom commands and subagents
1 parent d8f640d commit f30b546

File tree

2 files changed

+279
-0
lines changed

2 files changed

+279
-0
lines changed

‎.github/workflows/claude.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ on:
77
types: [created]
88
issues:
99
types: [opened, assigned, edited]
10+
1011
jobs:
1112
claude:
1213
runs-on: ubuntu-latest

‎docs/codeagent-v0.6-design.md

Lines changed: 278 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,278 @@
1+
# CodeAgent v0.6 - 自定义命令、Subagents 支持
2+
3+
## 背景认知
4+
5+
通过调研，我们知道要想让 AI 写代码效果更好，应该:
6+
7+
- 优化指令，让 AI 做事更有针对性，比如一个阶段只敢一件事
8+
- 使用 Extended Thinking 模式，主动让 AI 更充分的思考(claude)
9+
- 使用 Subagents ，构建专业 Agent，让其做特定的事
10+
- 基于实际场景，使用一些被证明行之有效的工作流
11+
- explore, plan,code , commit
12+
- Write tests, commit; code, iterate, commit
13+
- Write code, screenshot result, iterate
14+
- 使用高级的模型，如 Opus 4.1
15+
16+
结合上述行为在 claude code 侧的实际设计(PS: [gemini 相关能力能力还在开发中](https://github.com/google-gemini/gemini-cli/issues/3132) )，v0.6 计划引入了**自定义命令系统**和**Subagents 支持**，以充分利用 claude code 的能力。
17+
18+
设计要点:
19+
20+
- 在 github 交互中用到的 slash 命令，就类比 claude code 的命令。其最终对应的 prompt 细节都会映射到目录文件，类似/code 命令，会映射到 .codeagent/commands/code.md
21+
22+
- 命令格式，采用 YAML frontmatter + markdown 格式, 整体语法跟 claude code 一致
23+
24+
- 支持在命令里引入 GITHUB 上下文，该信息会统一由 CodeAgents 自动注入
25+
26+
- 支持 Claude Code 的 subagents 设计，最终命令文件也会挂载到合适的位置，如 .claude/commands、.claude/agents/
27+
28+
- 支持各仓库自定义命令，如果自定义命令跟系统默认重名，优先选择自定义命令
29+
30+
有了上述能力，我们就可以并行的，更加充分的调试 Prompt，探索最佳 AI 工作流实践。
31+
32+
## 命令示例
33+
34+
/analyze
35+
36+
```markdown
37+
---
38+
allowed-tools: all
39+
description: 需求深度分析
40+
model: ...
41+
---
42+
43+
## 当前 Issue 信息
44+
45+
- 仓库: $REPOSITORY
46+
- Issue: #$ISSUE_NUMBER - $ISSUE_TITLE
47+
- 提交者: $TRIGGER_USERNAME
48+
49+
## Issue 描述
50+
51+
$ISSUE_BODY
52+
53+
## 历史讨论
54+
55+
$ISSUE_COMMENTS
56+
57+
## 分析任务
58+
59+
请使用 Extended Thinking 模式对 Issue 进行深度分析
60+
```
61+
62+
#### Agent 定义格式示例
63+
64+
requirements-analyst agent:
65+
66+
```markdown
67+
---
68+
name: requirements-analyst
69+
description: "专业的需求分析专家"
70+
model: ...
71+
tools: ["read", "grep"]
72+
---
73+
74+
# 需求分析专家
75+
76+
你是一个经验丰富的需求分析专家，专注于理解和分析软件需求...
77+
78+
## 专业技能
79+
80+
- 深度需求理解和澄清
81+
- 技术可行性评估
82+
- 实现风险识别
83+
84+
## 工作方法
85+
86+
使用结构化分析方法，提供清晰准确的需求总结和实现建议
87+
```
88+
89+
对于 agent 的定义， claude code 要求:
90+
91+
| Field | Required | Description |
92+
| ----------- | -------- | ------------------------------------------------------------------------------------------- |
93+
| name | Yes | Unique identifier using lowercase letters and hyphens |
94+
| description | Yes | Natural language description of the subagent's purpose |
95+
| tools | No | Comma-separated list of specific tools. If omitted, inherits all tools from the main thread |
96+
97+
### 2. 目录结构
98+
99+
#### 2.1 配置文件
100+
101+
```yaml
102+
# config.yaml
103+
commands:
104+
global_path: "/opt/codeagent/.codeagent" # 保存agent默认的全局命令和Agent定义目录
105+
106+
# 其他配置...
107+
```
108+
109+
#### 2.2 目录合并机制
110+
111+
CodeAgent 在运行时将两个 `.codeagent` 目录**物理合并**成一个临时目录，然后挂载到容器：
112+
113+
**合并流程**：
114+
115+
```bash
116+
# 1. 创建临时合并目录
117+
mkdir /tmp/codeagent-merged-${repo}-${timestamp}
118+
119+
# 2. 先拷贝全局配置
120+
cp -r /opt/codeagent/.codeagent/* /tmp/codeagent-merged-${repo}/
121+
122+
# 3. 仓库配置覆盖全局配置（cp -rf 语义）
123+
if [ -d "${workspace}/.codeagent" ]; then
124+
cp -rf ${workspace}/.codeagent/* /tmp/codeagent-merged-${repo}/
125+
fi
126+
127+
# 4. 挂载到容器
128+
docker run -v /tmp/codeagent-merged-${repo}/commands:/root/.claude/commands \
129+
-v /tmp/codeagent-merged-${repo}/agents:/root/.claude/agents \
130+
...
131+
```
132+
133+
**实际效果**：
134+
135+
- 全局有 `analyze.md`, `plan.md`, `code.md`
136+
- 仓库有 `analyze.md`, `custom.md`
137+
- 合并后：`analyze.md`(仓库版本), `plan.md`(全局版本), `code.md`(全局版本), `custom.md`(仓库版本)
138+
139+
#### 2.3 目录层级
140+
141+
```
142+
# 全局配置目录（通过config.yaml指定）
143+
/opt/codeagent/.codeagent/
144+
├── commands/ # 命令定义文件 (.md)
145+
│ ├── analyze.md
146+
│ ├── plan.md
147+
│ ├── code.md
148+
│ ├── plan-and-code.md
149+
│ └── continue.md
150+
└── agents/ # Agent 定义文件 (.md)
151+
├── requirements-analyst.md
152+
├── solution-architect.md
153+
├── implementation-expert.md
154+
└── code-reviewer.md
155+
156+
# 仓库级配置目录（仓库根目录下，可选）
157+
{workspace}/.codeagent/
158+
├── commands/ # 项目特定命令（与全局合并，仓库级覆盖全局级）
159+
└── agents/ # 项目特定 agents（与全局合并，仓库级覆盖全局级）
160+
161+
# 运行时挂载
162+
Docker 模式：
163+
.codeagent/commands → ~/.claude/commands
164+
.codeagent/agents → ~/.claude/agents
165+
166+
```
167+
168+
### 3. 核心实现：GitHub 上下文注入器
169+
170+
**设计理念**：提供智能的模板引擎，支持简单变量替换和 Go Template 语法，适配不同事件类型的精确上下文。
171+
172+
#### 3.1 变量命名规范
173+
174+
采用 `GITHUB_` 前缀，类似如下：
175+
176+
```go
177+
// 核心变量
178+
$GITHUB_REPOSITORY // owner/repo
179+
$GITHUB_EVENT_TYPE // issues|pull_request|pull_request_review_comment
180+
$GITHUB_TRIGGER_USER // 触发用户
181+
182+
// Issue变量
183+
$GITHUB_ISSUE_NUMBER // 123
184+
$GITHUB_ISSUE_TITLE // Issue标题
185+
$GITHUB_ISSUE_BODY // Issue内容
186+
187+
// PR变量
188+
$GITHUB_PR_NUMBER // 456
189+
$GITHUB_PR_TITLE // PR标题
190+
$GITHUB_BRANCH_NAME // feature-branch
191+
$GITHUB_BASE_BRANCH // main
192+
193+
// Review Comment变量（高精度行级上下文）
194+
$GITHUB_REVIEW_FILE_PATH // src/main.go
195+
$GITHUB_REVIEW_LINE_RANGE // "行号：123" 或 "行号范围：45-67"
196+
$GITHUB_REVIEW_COMMENT_BODY // 评论内容
197+
$GITHUB_REVIEW_DIFF_HUNK // 差异片段
198+
$GITHUB_REVIEW_FILE_CONTENT // 目标行周围代码上下文
199+
```
200+
201+
#### 3.4 模板语法示例
202+
203+
```markdown
204+
# 智能事件分析
205+
206+
## 基本信息
207+
208+
- 仓库: {{.GITHUB_REPOSITORY}}
209+
- 事件: {{.GITHUB_EVENT_TYPE}}
210+
211+
## 上下文
212+
213+
{{if .GITHUB_IS_PR}}
214+
215+
### PR 信息
216+
217+
- PR #{{.GITHUB_PR_NUMBER}}: {{.GITHUB_PR_TITLE}}
218+
{{if gt (len .GITHUB_CHANGED_FILES) 10}}
219+
- 变更文件: {{len .GITHUB_CHANGED_FILES}}个（显示前 10 个）
220+
{{else}}
221+
- 变更文件: {{len .GITHUB_CHANGED_FILES}}个
222+
{{end}}
223+
{{else if .GITHUB_IS_ISSUE}}
224+
225+
### Issue 信息
226+
227+
- Issue #{{.GITHUB_ISSUE_NUMBER}}: {{.GITHUB_ISSUE_TITLE}}
228+
- 标签: {{join .GITHUB_ISSUE_LABELS ", "}}
229+
{{end}}
230+
```
231+
232+
GITHUb 上下文会基于后续需求，不断补充和调整。
233+
234+
## 内置命令设计
235+
236+
CodeAgent v0.6 预计会提供以下核心命令，支持从需求分析到代码实现的完整工作流：
237+
238+
### Issue 阶段命令
239+
240+
#### `/analyze` - 深度需求分析
241+
242+
- **用途**: 深入理解 Issue 需求，识别技术挑战和实现风险
243+
- **Subagent**: requirements-analyst
244+
- **GitHub 变量**: Issue 相关上下文（标题、内容、评论、标签等）
245+
- **输出**: 结构化的需求分析报告，包含技术难点和实施建议
246+
247+
#### `/plan` - 技术方案设计
248+
249+
- **用途**: 制定详细的技术实现方案和分步执行计划
250+
- **Subagent**: solution-architect
251+
- **GitHub 变量**: Issue 上下文 + 代码库结构信息
252+
- **输出**: 完整的技术方案文档，包含架构设计和实施清单
253+
254+
#### `/code` - 直接代码实现
255+
256+
- **用途**: 完整实现 Issue 需求，包含编码、测试、文档
257+
- **Subagent**: implementation-expert
258+
- **GitHub 变量**: Issue 上下文
259+
- **输出**: 可运行的代码实现 + 测试 + 文档
260+
261+
### PR 阶段命令
262+
263+
#### `/continue` - PR 协作开发
264+
265+
- **用途**: 在 PR 中处理反馈、迭代改进、解决问题
266+
- **Subagent**: pr-collaborator
267+
- **GitHub 变量**: PR 完整上下文（变更文件、评论历史、Review 反馈等）
268+
- **输出**: 改进后的代码 + 反馈回应 + 变更说明
269+
270+
## 参考资料
271+
272+
- https://www.anthropic.com/engineering/claude-code-best-practices
273+
- https://docs.anthropic.com/en/docs/claude-code/sub-agents
274+
- https://docs.anthropic.com/en/docs/claude-code/slash-commands
275+
- https://github.com/cexll/myclaude
276+
- https://github.com/anthropics/claude-code-security-review
277+
- https://github.com/anthropics/claude-code-action
278+
- https://github.com/Pimzino/claude-code-spec-workflow

0 commit comments

Comments
 (0)