Skip to content

Commit 3db08db

Browse files
CodeCasterXclaude
andcommitted
refactor: 重构 .ai-workspace 目录结构,合并任务和上下文文件
将任务文件和上下文文件合并到一起,按状态组织,提升信息检索效率。 ## 主要变更 ### 1. 目录结构重构 - 旧结构:tasks/{status}/ + context/{task-id}/ - 新结构:{status}/{task-id}/ (包含 task.md + context files) ### 2. 文件重命名 - {task-id}.md → {task-id}/task.md ### 3. 配置文件更新(22 个) - 命令文件:8 个 (.claude/commands/) - 核心文档:4 个 (.ai-agents/README.md, QUICKSTART.md, .claude/project-rules.md, QUICK-REFERENCE.md) - 工作流文件:4 个 (.ai-agents/workflows/) - 模板文件:3 个 (.ai-agents/templates/) - AI 工具配置:3 个 (.ai-agents/*/README.md) ### 4. Bug 修复 - sync-issue.md line 35-36: 修复文件名 typo (plan-task.md → plan.md, implement-taskation.md → implementation.md) ## 迁移详情 - 迁移任务:5 个 (2 active + 3 completed) - 迁移上下文文件:约 20 个 - 备份位置:见 .ai-workspace/migration-report.md ## 新目录结构 ``` .ai-workspace/ ├── active/ │ └── TASK-{id}/ │ ├── task.md │ ├── analysis.md │ ├── plan.md │ ├── implementation.md │ └── review.md ├── completed/ │ └── TASK-{id}/ │ └── task.md + context files └── blocked/ └── TASK-{id}/ └── task.md + context files ``` ## 向后兼容性 ⚠️ 破坏性变更:所有引用旧路径的脚本和命令需要更新。 ## 回滚方法 见 .ai-workspace/migration-report.md Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
1 parent 8dae1bf commit 3db08db

22 files changed

Lines changed: 170 additions & 161 deletions

.ai-agents/QUICKSTART.md

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88

99
```bash
1010
# 复制任务模板
11-
cp .ai-agents/templates/task.md .ai-workspace/tasks/active/TASK-{yyyyMMdd}-{task-id}.md
11+
cp .ai-agents/templates/task.md .ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/task.md
1212
```
1313

1414
编辑任务文件,填写:
@@ -20,13 +20,13 @@ cp .ai-agents/templates/task.md .ai-workspace/tasks/active/TASK-{yyyyMMdd}-{task
2020

2121
在 Claude Code 中:
2222
```
23-
请分析 .ai-workspace/tasks/active/TASK-{yyyyMMdd}-{task-id}.md 中的任务
23+
请分析 .ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/task.md 中的任务
2424
```
2525

2626
Claude 会:
2727
1. 读取任务描述
2828
2. 分析相关代码
29-
3. 创建需求分析报告:`.ai-workspace/context/TASK-{yyyyMMdd}-{task-id}/analysis.md`
29+
3. 创建需求分析报告:`.ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/analysis.md`
3030

3131
### 3. Claude 设计技术方案
3232

@@ -35,23 +35,23 @@ Claude 会:
3535
```
3636

3737
Claude 会创建:
38-
- `.ai-workspace/context/TASK-{yyyyMMdd}-{task-id}/plan.md`
38+
- `.ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/plan.md`
3939

4040
**人工检查点**:审查方案是否合理
4141

4242
### 4. 切换到 ChatGPT 实现代码
4343

4444
在 ChatGPT/Cursor 中:
4545
```
46-
请根据 .ai-workspace/tasks/active/TASK-{yyyyMMdd}-{task-id}.md 实现代码。
47-
参考方案:.ai-workspace/context/TASK-{yyyyMMdd}-{task-id}/plan.md
46+
请根据 .ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/task.md 实现代码。
47+
参考方案:.ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/plan.md
4848
```
4949

5050
ChatGPT 会:
5151
1. 读取任务和方案
5252
2. 编写代码实现
5353
3. 编写单元测试
54-
4. 创建实现报告:`.ai-workspace/context/TASK-{yyyyMMdd}-{task-id}/implementation.md`
54+
4. 创建实现报告:`.ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/implementation.md`
5555

5656
### 5. 切换回 Claude 审查代码
5757

@@ -63,7 +63,7 @@ ChatGPT 会:
6363
Claude 会:
6464
1. 读取实现报告
6565
2. 审查代码变更
66-
3. 创建审查报告:`.ai-workspace/context/TASK-{yyyyMMdd}-{task-id}/review.md`
66+
3. 创建审查报告:`.ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/review.md`
6767

6868
### 6. 根据审查结果决定
6969

@@ -83,7 +83,7 @@ Claude 会:
8383

8484
```bash
8585
# 1. 创建 Bug 任务
86-
cp .ai-agents/templates/task.md .ai-workspace/tasks/active/BUG-{yyyyMMdd}-{task-id}.md
86+
cp .ai-agents/templates/task.md .ai-workspace/active/BUG-{yyyyMMdd}-{task-id}/task.md
8787
# 编辑:type: bugfix, workflow: bug-fix
8888

8989
# 2. Claude 分析 Bug
@@ -96,14 +96,14 @@ cp .ai-agents/templates/task.md .ai-workspace/tasks/active/BUG-{yyyyMMdd}-{task-
9696
"请审查 BUG-{yyyyMMdd}-{task-id} 的修复"
9797

9898
# 5. 提交
99-
/commitcp .ai-agents/templates/task.md .ai-workspace/tasks/active/BUG-{yyyyMMdd}-{task-id}.md
99+
/commitcp .ai-agents/templates/task.md .ai-workspace/active/BUG-{yyyyMMdd}-{task-id}/task.md
100100
```
101101

102102
### 场景 2:代码审查
103103

104104
```bash
105105
# 1. 创建审查任务
106-
cp .ai-agents/templates/task.md .ai-workspace/tasks/active/REVIEW-PR-{task-id}.md
106+
cp .ai-agents/templates/task.md .ai-workspace/active/REVIEW-PR-{task-id}/task.md
107107
# 编辑:type: review, workflow: code-review
108108

109109
# 2. Claude 执行审查
@@ -118,7 +118,7 @@ cp .ai-agents/templates/task.md .ai-workspace/tasks/active/REVIEW-PR-{task-id}.m
118118

119119
```bash
120120
# 1. 创建重构任务
121-
cp .ai-agents/templates/task.md .ai-workspace/tasks/active/REFACTOR-{yyyyMMdd}-{task-id}.md
121+
cp .ai-agents/templates/task.md .ai-workspace/active/REFACTOR-{yyyyMMdd}-{task-id}/task.md
122122
# 编辑:type: refactor, workflow: refactoring
123123

124124
# 2. Claude 分析和规划
@@ -191,14 +191,14 @@ REVIEW-PR-{pr-number}.md # PR审查
191191

192192
**解决方案**:明确指定任务文件
193193
```
194-
请处理 .ai-workspace/tasks/active/TASK-{yyyyMMdd}-{task-id}.md
194+
请处理 .ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/task.md
195195
```
196196

197197
### 问题 2:上下文丢失
198198

199199
**解决方案**:检查 context 目录
200200
```bash
201-
ls -la .ai-workspace/context/TASK-{yyyyMMdd}-{task-id}/
201+
ls -la .ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/
202202
```
203203

204204
确保每个步骤都创建了输出文件。
@@ -207,7 +207,7 @@ ls -la .ai-workspace/context/TASK-{yyyyMMdd}-{task-id}/
207207

208208
**解决方案**:查看任务文件
209209
```bash
210-
cat .ai-workspace/tasks/active/TASK-{yyyyMMdd}-{task-id}.md
210+
cat .ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/task.md
211211
```
212212

213213
检查 `current_step``assigned_to` 字段。

.ai-agents/README.md

Lines changed: 23 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -23,16 +23,19 @@
2323
└── README.md
2424
2525
.ai-workspace/ # 工作目录(临时文件,被 git ignore)
26-
├── tasks/ # 任务状态跟踪
27-
│ ├── active/ # 进行中的任务
28-
│ ├── blocked/ # 被阻塞的任务
29-
│ └── completed/ # 已完成的任务
30-
├── context/ # 任务上下文共享
31-
│ └── {task-id}/ # 每个任务的上下文
32-
│ ├── analysis.md
33-
│ ├── plan.md
34-
│ ├── implementation.md
35-
│ └── review.md
26+
├── active/ # 进行中的任务
27+
│ └── {task-id}/
28+
│ ├── task.md # 任务主文件
29+
│ ├── analysis.md # 需求分析
30+
│ ├── plan.md # 技术方案
31+
│ ├── implementation.md # 实现报告
32+
│ └── review.md # 审查报告
33+
├── completed/ # 已完成的任务
34+
│ └── {task-id}/
35+
│ └── task.md + context files
36+
├── blocked/ # 被阻塞的任务
37+
│ └── {task-id}/
38+
│ └── task.md + context files
3639
└── logs/ # 执行日志
3740
```
3841

@@ -42,19 +45,19 @@
4245

4346
1. **需求分析**(推荐:Claude)
4447
- 理解需求,分析现有代码
45-
- 输出:`.ai-workspace/context/{task-id}/analysis.md`
48+
- 输出:`.ai-workspace/active/{task-id}/analysis.md`
4649

4750
2. **方案设计**(推荐:Claude)
4851
- 设计技术方案,制定计划
49-
- 输出:`.ai-workspace/context/{task-id}/plan.md`
52+
- 输出:`.ai-workspace/active/{task-id}/plan.md`
5053

5154
3. **代码实现**(推荐:ChatGPT/Gemini/Cursor)
5255
- 根据方案编写代码和测试
53-
- 输出:`.ai-workspace/context/{task-id}/implementation.md`
56+
- 输出:`.ai-workspace/active/{task-id}/implementation.md`
5457

5558
4. **代码审查**(推荐:Claude)
5659
- 审查代码质量、安全性、性能
57-
- 输出:`.ai-workspace/context/{task-id}/review.md`
60+
- 输出:`.ai-workspace/active/{task-id}/review.md`
5861

5962
5. **问题修复**(任意 AI)
6063
- 根据审查意见修复问题
@@ -110,19 +113,19 @@
110113
### 灵活切换 AI
111114

112115
任何 AI 都可以通过读取以下内容接手任务:
113-
- 任务文件:`.ai-workspace/tasks/active/{task-id}.md`
114-
- 上下文:`.ai-workspace/context/{task-id}/`
116+
- 任务文件:`.ai-workspace/active/{task-id}/task.md`
117+
- 上下文:`.ai-workspace/active/{task-id}/`
115118

116119
## 🚀 快速开始
117120

118121
### 1. 创建新任务
119122

120123
```bash
121124
# 复制任务模板
122-
cp .ai-agents/templates/task.md .ai-workspace/tasks/active/TASK-{task-id}.md
125+
cp .ai-agents/templates/task.md .ai-workspace/active/TASK-{task-id}/task.md
123126

124127
# 编辑任务描述
125-
vim .ai-workspace/tasks/active/TASK-{task-id}.md
128+
vim .ai-workspace/active/TASK-{task-id}/task.md
126129
```
127130

128131
### 2. 使用 AI 分析
@@ -144,7 +147,7 @@ Claude 会:
144147

145148
在 Cursor/ChatGPT/Gemini 中:
146149
```
147-
根据 .ai-workspace/tasks/active/TASK-{task-id}.md 实现代码
150+
根据 .ai-workspace/active/TASK-{task-id}/task.md 实现代码
148151
```
149152

150153
AI 会:
@@ -237,7 +240,7 @@ GPT 和 Cursor 的配置在 `.ai-agents/gpt/` 目录。
237240

238241
### 上下文管理
239242

240-
- `.ai-workspace/context/` 包含任务的完整上下文
243+
- `.ai-workspace/{status}/{task-id}/` 包含任务的完整上下文
241244
- 切换 AI 时,新的 AI 会读取这些文件了解进度
242245
- 保持文档完整和准确,便于协作
243246

.ai-agents/chatgpt/README.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
当人类切换到 ChatGPT 时:
2222

2323
```
24-
请根据 .ai-workspace/tasks/active/TASK-{id}.md 继续工作
24+
请根据 .ai-workspace/active/TASK-{id}/task.md 继续工作
2525
```
2626

2727
ChatGPT 应该:
@@ -42,7 +42,7 @@ ChatGPT 擅长的任务:
4242

4343
**示例提示词**:
4444
```
45-
请根据 .ai-workspace/context/TASK-{id}/plan.md 中的方案实现代码。
45+
请根据 .ai-workspace/active/TASK-{id}/plan.md 中的方案实现代码。
4646
需要包括:
4747
1. 功能实现
4848
2. 单元测试
@@ -66,7 +66,7 @@ ChatGPT 擅长的任务:
6666

6767
完成任务后,ChatGPT 应该:
6868

69-
1. 创建输出文件到 `.ai-workspace/context/{task-id}/`
69+
1. 创建输出文件到 `.ai-workspace/active/{task-id}/`
7070
2. 更新任务状态
7171
3. 说明完成情况和需要注意的事项
7272

@@ -171,10 +171,10 @@ ChatGPT 和 Gemini 可以互为替代:
171171
## 常见问题
172172

173173
### Q: 如何知道现在该做什么?
174-
A: 查看 `.ai-workspace/tasks/active/` 下的任务文件
174+
A: 查看 `.ai-workspace/active/` 下的任务目录
175175

176176
### Q: 找不到上下文信息?
177-
A: 检查 `.ai-workspace/context/{task-id}/` 目录
177+
A: 检查 `.ai-workspace/active/{task-id}/` 目录
178178

179179
### Q: 任务文件中的 workflow 是什么?
180180
A: 查看 `.ai-agents/workflows/{workflow}.yaml` 了解完整流程

.ai-agents/cursor/README.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Cursor 是一个 AI 驱动的代码编辑器,基于 VSCode,集成了多种 A
1414

1515
1. 读取 `AGENTS.md`(项目根目录)了解项目基本信息
1616
2. 读取 `.ai-agents/README.md` 了解协作流程
17-
3. 读取 `.ai-workspace/tasks/active/` 中的任务
17+
3. 读取 `.ai-workspace/active/` 中的任务
1818

1919
### 2. 在 Cursor 中工作
2020

@@ -50,13 +50,13 @@ Cursor 特别适合:
5050

5151
```
5252
# 查看当前任务
53-
cat .ai-workspace/tasks/active/TASK-{id}.md
53+
cat .ai-workspace/active/TASK-{id}/task.md
5454
5555
# 查看技术方案
56-
cat .ai-workspace/context/{task-id}/plan.md
56+
cat .ai-workspace/active/{task-id}/plan.md
5757
5858
# 完成后创建实现报告
59-
# 编辑 .ai-workspace/context/{task-id}/implementation.md
59+
# 编辑 .ai-workspace/active/{task-id}/implementation.md
6060
```
6161

6262
### 5. 配置建议

.ai-agents/gemini/README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
当人类切换到 Gemini 时:
2222

2323
```
24-
请根据 .ai-workspace/tasks/active/TASK-{id}.md 继续工作
24+
请根据 .ai-workspace/active/TASK-{id}/task.md 继续工作
2525
```
2626

2727
Gemini 应该:
@@ -65,7 +65,7 @@ Gemini 应该:
6565
### 5. 完成任务后
6666

6767
完成任务后,Gemini 应该:
68-
1. 创建输出文件到 `.ai-workspace/context/{task-id}/`
68+
1. 创建输出文件到 `.ai-workspace/active/{task-id}/`
6969
2. 更新任务状态
7070
3. 说明完成情况
7171

.ai-agents/templates/handoff.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -65,8 +65,8 @@
6565
### 输入资源
6666

6767
接手的AI需要读取:
68-
- [ ] `.ai-workspace/tasks/active/TASK-{id}.md` - 任务文件
69-
- [ ] `.ai-workspace/context/{task-id}/{file}.md` - 上下文文件
68+
- [ ] `.ai-workspace/active/TASK-{id}/task.md` - 任务文件
69+
- [ ] `.ai-workspace/active/{task-id}/{file}.md` - 上下文文件
7070
- [ ] {其他相关文件}
7171

7272
## 上下文说明

.ai-agents/templates/task.md

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -29,10 +29,10 @@ assigned_to: {当前处理的AI或空}
2929

3030
请阅读以下文件了解任务完整上下文:
3131

32-
- [ ] `.ai-workspace/context/{task-id}/analysis.md` - 需求分析
33-
- [ ] `.ai-workspace/context/{task-id}/plan.md` - 技术方案
34-
- [ ] `.ai-workspace/context/{task-id}/implementation.md` - 实现报告
35-
- [ ] `.ai-workspace/context/{task-id}/review.md` - 审查报告
32+
- [ ] `.ai-workspace/active/{task-id}/analysis.md` - 需求分析
33+
- [ ] `.ai-workspace/active/{task-id}/plan.md` - 技术方案
34+
- [ ] `.ai-workspace/active/{task-id}/implementation.md` - 实现报告
35+
- [ ] `.ai-workspace/active/{task-id}/review.md` - 审查报告
3636

3737
## 相关资源
3838

@@ -76,12 +76,12 @@ assigned_to: {当前处理的AI或空}
7676

7777
### 输入文件
7878

79-
- `.ai-workspace/context/{task-id}/{input-file}.md`
79+
- `.ai-workspace/active/{task-id}/{input-file}.md`
8080

8181
### 输出要求
8282

8383
完成后创建/更新:
84-
- `.ai-workspace/context/{task-id}/{output-file}.md`
84+
- `.ai-workspace/active/{task-id}/{output-file}.md`
8585

8686
包含以下章节:
8787
- {section-1}
@@ -138,7 +138,7 @@ assigned_to: {当前处理的AI或空}
138138

139139
### 遇到问题怎么办
140140

141-
1. 将任务移到 `.ai-workspace/tasks/blocked/`
141+
1. 将任务目录移到 `.ai-workspace/blocked/`
142142
2. 在任务中添加"阻塞原因"章节
143143
3. 说明遇到的问题和需要的帮助
144144
4. 通知人类用户

.ai-agents/workflows/bug-fix.yaml

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ steps:
2626
- "评估影响范围"
2727

2828
outputs:
29-
- path: ".ai-workspace/context/{task-id}/bug-analysis.md"
29+
- path: ".ai-workspace/{status}/{task-id}/bug-analysis.md"
3030
required_sections:
3131
- "Bug描述": "现象、复现步骤、预期行为"
3232
- "根本原因": "问题的根本原因分析"
@@ -52,7 +52,7 @@ steps:
5252
reason: "处理复杂bug修复"
5353

5454
inputs:
55-
- path: ".ai-workspace/context/{task-id}/bug-analysis.md"
55+
- path: ".ai-workspace/{status}/{task-id}/bug-analysis.md"
5656

5757
tasks:
5858
- "修复bug"
@@ -61,7 +61,7 @@ steps:
6161
- "检查是否有类似问题"
6262

6363
outputs:
64-
- path: ".ai-workspace/context/{task-id}/bug-fix.md"
64+
- path: ".ai-workspace/{status}/{task-id}/bug-fix.md"
6565
required_sections:
6666
- "修复说明": "如何修复的"
6767
- "测试验证": "测试结果"
@@ -84,15 +84,15 @@ steps:
8484
reason: "擅长审查和风险评估"
8585

8686
inputs:
87-
- path: ".ai-workspace/context/{task-id}/bug-fix.md"
87+
- path: ".ai-workspace/{status}/{task-id}/bug-fix.md"
8888

8989
tasks:
9090
- "审查修复方案"
9191
- "检查是否引入新问题"
9292
- "评估测试覆盖"
9393

9494
outputs:
95-
- path: ".ai-workspace/context/{task-id}/review.md"
95+
- path: ".ai-workspace/{status}/{task-id}/review.md"
9696

9797
next_steps:
9898
- "finalize"

0 commit comments

Comments
 (0)