Skip to content

Commit 9a9383d

Browse files
CodeCasterXclaude
CodeCasterX
and
claude
committed
docs: 更新 AGENTS/GEMINI 文档以反映最新的目录结构和命令
**更新内容**： - 修正 .ai-workspace/ 目录结构说明 - 从 tasks/active/, tasks/blocked/, tasks/completed/ - 更新为 active/, blocked/, completed/（任务文件和上下文合并） - 添加 logs/ 目录说明 - 更新标准协作流程，补充新增的命令 - 添加 /refinement-task 步骤 - 添加 /complete-task 归档步骤 - 添加 /block-task 阻塞处理步骤 - 每个步骤明确对应的命令 - 更新任务跟踪部分 - 使用 Slash Commands 代替手动复制模板 - 添加新的任务目录结构图 - 强调状态更新要求（CRITICAL） - 更新详细文档链接 - 添加 QUICKSTART.md - 添加 project-rules.md（规则 7） - 添加 commands/ 目录参考 - 补充版权年份更新说明 - GEMINI.md/en 缺少该说明，现已添加 **影响范围**： - AGENTS.md（中文） - 70 行变更 - AGENTS.en.md（英文） - 68 行变更 - GEMINI.md（中文） - 75 行变更 - GEMINI.en.md（英文） - 69 行变更 **相关提交**： - ce4eb0e feat: 增强任务状态管理，新增工作流命令并完善状态追踪 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
1 parent ce4eb0e commit 9a9383d

4 files changed

Lines changed: 214 additions & 68 deletions

File tree

‎AGENTS.en.md‎

Lines changed: 52 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -56,52 +56,85 @@ This project supports collaboration among multiple AI tools (Claude, GPT, Cursor
5656
- `cursor/` - Cursor-specific config
5757

5858
- **`.ai-workspace/`** - Collaboration workspace (temporary, gitignored)
59-
- `tasks/active/` - Tasks in progress
60-
- `tasks/blocked/` - Blocked tasks
61-
- `tasks/completed/` - Completed tasks
62-
- `context/{task-id}/` - Task context files
59+
- `active/` - Tasks in progress (with task files and context)
60+
- `blocked/` - Blocked tasks
61+
- `completed/` - Completed tasks
62+
- `logs/` - Collaboration logs and records
6363

6464
### Standard Collaboration Flow
6565

6666
Recommended (but not mandatory) workflow:
6767

6868
1. **Requirement Analysis** (Recommended: Claude)
69+
- Use `/analyze-issue <issue-number>` command
6970
- Understand requirements, analyze code, assess impact
70-
- Output: `context/{task-id}/analysis.md`
71+
- Output: `active/{task-id}/analysis.md`
7172

7273
2. **Technical Design** (Recommended: Claude)
74+
- Use `/plan-task <task-id>` command
7375
- Design technical solution, create implementation plan
74-
- Output: `context/{task-id}/plan.md`
76+
- Output: `active/{task-id}/plan.md`
7577
- ⚠️ **Human Checkpoint**: Review the plan
7678

7779
3. **Implementation** (Recommended: ChatGPT/Gemini/Cursor)
80+
- Use `/implement-task <task-id>` command
7881
- Write code and unit tests
79-
- Output: `context/{task-id}/implementation.md`
82+
- Output: `active/{task-id}/implementation.md`
8083

8184
4. **Code Review** (Recommended: Claude)
85+
- Use `/review-task <task-id>` command
8286
- Review quality, security, performance
83-
- Output: `context/{task-id}/review.md`
87+
- Output: `active/{task-id}/review.md`
8488

8589
5. **Refinement** (Any AI)
90+
- Use `/refinement-task <task-id>` command
8691
- Address review comments
92+
- Output: `active/{task-id}/refinement-report.md`
8793

88-
6. **Finalize** (Human confirmation)
89-
- ⚠️ **Human Checkpoint**: Confirm before commit
94+
6. **Task Completion** (Recommended: Claude)
95+
- Use `/complete-task <task-id>` command
96+
- ⚠️ **Human Checkpoint**: Confirm before archiving
97+
- Task moved to `completed/` directory
98+
99+
7. **Blocking Handling** (Special cases)
100+
- Use `/block-task <task-id> --reason <reason>` command
101+
- Task moved to `blocked/` directory
102+
- Record blocking reason and needed help
90103

91104
### Task Tracking
92105

93-
Create a task:
106+
**Use Slash Commands to create and manage tasks**:
94107
```bash
95-
cp .ai-agents/templates/task.md .ai-workspace/tasks/active/TASK-$(date +%Y%m%d-%H%M%S).md
108+
# Analyze Issue and create task
109+
/analyze-issue <issue-number>
110+
111+
# View task status
112+
/task-status <task-id>
113+
114+
# Sync to GitHub Issue
115+
/sync-issue <issue-number>
116+
```
117+
118+
**Task directory structure**:
119+
```
120+
.ai-workspace/
121+
├── active/TASK-{timestamp}/ # Tasks in progress
122+
│ ├── task.md # Task metadata
123+
│ ├── analysis.md # Requirements analysis
124+
│ ├── plan.md # Technical design
125+
│ ├── implementation.md # Implementation report
126+
│ └── review.md # Code review report
127+
├── blocked/TASK-{timestamp}/ # Blocked tasks
128+
└── completed/TASK-{timestamp}/ # Completed tasks
96129
```
97130

98131
AI picks up task:
99-
- Read task file: `.ai-workspace/tasks/active/TASK-*.md`
100-
- Read context: `.ai-workspace/context/{task-id}/`
132+
- Read task file: `.ai-workspace/active/{task-id}/task.md`
133+
- Read context files: `active/{task-id}/`
101134
- Complete task checklist
102-
- Create output files
135+
- Update task status (CRITICAL: see Rule 7)
103136

104-
AI handoff: Any AI can take over by reading the context directory.
137+
AI handoff: Any AI can take over by reading the task directory.
105138

106139
### AI Capabilities Reference
107140

@@ -115,8 +148,11 @@ AI handoff: Any AI can take over by reading the context directory.
115148
### Detailed Documentation
116149

117150
- Collaboration Guide: `.ai-agents/README.md`
151+
- Quick Start: `.ai-agents/QUICKSTART.md`
118152
- Workflow Definitions: `.ai-agents/workflows/`
119153
- Claude Config: `.claude/README.md`
154+
- Claude Project Rules: `.claude/project-rules.md` (includes Rule 7: Task Status Management)
155+
- Claude Command Reference: `.claude/commands/`
120156
- ChatGPT Config: `.ai-agents/chatgpt/README.md`
121157
- Gemini Config: `.ai-agents/gemini/README.md`
122158

‎AGENTS.md‎

Lines changed: 53 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -56,52 +56,85 @@
5656
- `cursor/` - Cursor 专用配置
5757

5858
- **`.ai-workspace/`** - 协作工作区（临时文件，已 ignore）
59-
- `tasks/active/` - 进行中的任务
60-
- `tasks/blocked/` - 被阻塞的任务
61-
- `tasks/completed/` - 已完成的任务
62-
- `context/{task-id}/` - 任务上下文文件
59+
- `active/` - 进行中的任务（包含任务文件和上下文）
60+
- `blocked/` - 被阻塞的任务
61+
- `completed/` - 已完成的任务
62+
- `logs/` - 协作日志和记录
6363

6464
### 标准协作流程
6565

6666
推荐（但非强制）的工作流程：
6767

6868
1. **需求分析**（推荐：Claude）
69+
- 使用 `/analyze-issue <issue-number>` 命令
6970
- 理解需求，分析代码，评估影响
70-
- 输出：`context/{task-id}/analysis.md`
71+
- 输出：`active/{task-id}/analysis.md`
7172

7273
2. **方案设计**（推荐：Claude）
74+
- 使用 `/plan-task <task-id>` 命令
7375
- 设计技术方案，制定实施计划
74-
- 输出：`context/{task-id}/plan.md`
76+
- 输出：`active/{task-id}/plan.md`
7577
- ⚠️ **人工检查点**：审查方案
7678

7779
3. **代码实现**（推荐：ChatGPT/Gemini/Cursor）
80+
- 使用 `/implement-task <task-id>` 命令
7881
- 编写代码和单元测试
79-
- 输出：`context/{task-id}/implementation.md`
82+
- 输出：`active/{task-id}/implementation.md`
8083

8184
4. **代码审查**（推荐：Claude）
85+
- 使用 `/review-task <task-id>` 命令
8286
- 审查质量、安全、性能
83-
- 输出：`context/{task-id}/review.md`
87+
- 输出：`active/{task-id}/review.md`
8488

8589
5. **问题修复**（任意 AI）
86-
- 根据审查意见改进
90+
- 使用 `/refinement-task <task-id>` 命令
91+
- 根据审查意见改进代码
92+
- 输出：`active/{task-id}/refinement-report.md`
8793

88-
6. **最终提交**（人工确认）
89-
- ⚠️ **人工检查点**：确认后提交
94+
6. **任务归档**（推荐：Claude）
95+
- 使用 `/complete-task <task-id>` 命令
96+
- ⚠️ **人工检查点**：确认后归档
97+
- 任务移动到 `completed/` 目录
98+
99+
7. **阻塞处理**（特殊情况）
100+
- 使用 `/block-task <task-id> --reason <原因>` 命令
101+
- 任务移动到 `blocked/` 目录
102+
- 记录阻塞原因和需要的帮助
90103

91104
### 任务跟踪
92105

93-
创建任务：
106+
**使用 Slash Commands 创建和管理任务**：
94107
```bash
95-
cp .ai-agents/templates/task.md .ai-workspace/tasks/active/TASK-$(date +%Y%m%d-%H%M%S).md
108+
# 分析 Issue 并创建任务
109+
/analyze-issue <issue-number>
110+
111+
# 查看任务状态
112+
/task-status <task-id>
113+
114+
# 同步到 GitHub Issue
115+
/sync-issue <issue-number>
116+
```
117+
118+
**任务目录结构**：
119+
```
120+
.ai-workspace/
121+
├── active/TASK-{timestamp}/ # 进行中的任务
122+
│ ├── task.md # 任务元数据
123+
│ ├── analysis.md # 需求分析
124+
│ ├── plan.md # 技术方案
125+
│ ├── implementation.md # 实现报告
126+
│ └── review.md # 审查报告
127+
├── blocked/TASK-{timestamp}/ # 被阻塞的任务
128+
└── completed/TASK-{timestamp}/ # 已完成的任务
96129
```
97130

98131
AI 接手任务：
99-
- 读取任务文件：`.ai-workspace/tasks/active/TASK-*.md`
100-
- 读取上下文：`.ai-workspace/context/{task-id}/`
132+
- 读取任务文件：`.ai-workspace/active/{task-id}/task.md`
133+
- 读取上下文文件：`active/{task-id}/`
101134
- 完成任务清单
102-
- 创建输出文件
135+
- 更新任务状态（CRITICAL：参见规则 7）
103136

104-
AI 切换：任何 AI 都可以通过读取 context 目录接手任务。
137+
AI 切换：任何 AI 都可以通过读取任务目录接手任务。
105138

106139
### AI 能力参考
107140

@@ -115,8 +148,11 @@ AI 切换：任何 AI 都可以通过读取 context 目录接手任务。
115148
### 详细文档
116149

117150
- 协作总指南：`.ai-agents/README.md`
151+
- 快速开始：`.ai-agents/QUICKSTART.md`
118152
- 工作流定义：`.ai-agents/workflows/`
119153
- Claude 配置：`.claude/README.md`
154+
- Claude 项目规则：`.claude/project-rules.md`（包含规则 7：任务状态管理规范）
155+
- Claude 命令参考：`.claude/commands/`
120156
- ChatGPT 配置：`.ai-agents/chatgpt/README.md`
121157
- Gemini 配置：`.ai-agents/gemini/README.md`
122158

‎GEMINI.en.md‎

Lines changed: 53 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ This repo hosts the FIT framework and related engines.
2121
- Java formatting uses the IntelliJ profile `CodeFormatterFromIdea.xml`.
2222
- Public/protected Java APIs require Javadoc with `@param`/`@return` tags.
2323
- Class headers must include `@author` and `@since yyyy-MM-dd`.
24+
- When modifying any file with a copyright header, you **must first obtain the current year using the system command `date +%Y`**, then update the copyright year accordingly (e.g., if current year is 2026: `2024-2025` → `2024-2026`, `2024` → `2024-2026`).
2425
- Branch naming follows module prefixes and intent, e.g. `fit-feature-xxx`, `waterflow-bugfix-yyy`.
2526

2627
## Testing Guidelines
@@ -55,52 +56,85 @@ This project supports collaboration among multiple AI tools (Claude, GPT, Cursor
5556
- `cursor/` - Cursor-specific config
5657

5758
- **`.ai-workspace/`** - Collaboration workspace (temporary, gitignored)
58-
- `tasks/active/` - Tasks in progress
59-
- `tasks/blocked/` - Blocked tasks
60-
- `tasks/completed/` - Completed tasks
61-
- `context/{task-id}/` - Task context files
59+
- `active/` - Tasks in progress (with task files and context)
60+
- `blocked/` - Blocked tasks
61+
- `completed/` - Completed tasks
62+
- `logs/` - Collaboration logs and records
6263

6364
### Standard Collaboration Flow
6465

6566
Recommended (but not mandatory) workflow:
6667

6768
1. **Requirement Analysis** (Recommended: Claude)
69+
- Use `/analyze-issue <issue-number>` command
6870
- Understand requirements, analyze code, assess impact
69-
- Output: `context/{task-id}/analysis.md`
71+
- Output: `active/{task-id}/analysis.md`
7072

7173
2. **Technical Design** (Recommended: Claude)
74+
- Use `/plan-task <task-id>` command
7275
- Design technical solution, create implementation plan
73-
- Output: `context/{task-id}/plan.md`
76+
- Output: `active/{task-id}/plan.md`
7477
- ⚠️ **Human Checkpoint**: Review the plan
7578

7679
3. **Implementation** (Recommended: ChatGPT/Gemini/Cursor)
80+
- Use `/implement-task <task-id>` command
7781
- Write code and unit tests
78-
- Output: `context/{task-id}/implementation.md`
82+
- Output: `active/{task-id}/implementation.md`
7983

8084
4. **Code Review** (Recommended: Claude)
85+
- Use `/review-task <task-id>` command
8186
- Review quality, security, performance
82-
- Output: `context/{task-id}/review.md`
87+
- Output: `active/{task-id}/review.md`
8388

8489
5. **Refinement** (Any AI)
90+
- Use `/refinement-task <task-id>` command
8591
- Address review comments
92+
- Output: `active/{task-id}/refinement-report.md`
8693

87-
6. **Finalize** (Human confirmation)
88-
- ⚠️ **Human Checkpoint**: Confirm before commit
94+
6. **Task Completion** (Recommended: Claude)
95+
- Use `/complete-task <task-id>` command
96+
- ⚠️ **Human Checkpoint**: Confirm before archiving
97+
- Task moved to `completed/` directory
98+
99+
7. **Blocking Handling** (Special cases)
100+
- Use `/block-task <task-id> --reason <reason>` command
101+
- Task moved to `blocked/` directory
102+
- Record blocking reason and needed help
89103

90104
### Task Tracking
91105

92-
Create a task:
106+
**Use Slash Commands to create and manage tasks**:
93107
```bash
94-
cp .ai-agents/templates/task.md .ai-workspace/tasks/active/TASK-$(date +%Y%m%d-%H%M%S).md
108+
# Analyze Issue and create task
109+
/analyze-issue <issue-number>
110+
111+
# View task status
112+
/task-status <task-id>
113+
114+
# Sync to GitHub Issue
115+
/sync-issue <issue-number>
116+
```
117+
118+
**Task directory structure**:
119+
```
120+
.ai-workspace/
121+
├── active/TASK-{timestamp}/ # Tasks in progress
122+
│ ├── task.md # Task metadata
123+
│ ├── analysis.md # Requirements analysis
124+
│ ├── plan.md # Technical design
125+
│ ├── implementation.md # Implementation report
126+
│ └── review.md # Code review report
127+
├── blocked/TASK-{timestamp}/ # Blocked tasks
128+
└── completed/TASK-{timestamp}/ # Completed tasks
95129
```
96130

97131
AI picks up task:
98-
- Read task file: `.ai-workspace/tasks/active/TASK-*.md`
99-
- Read context: `.ai-workspace/context/{task-id}/`
132+
- Read task file: `.ai-workspace/active/{task-id}/task.md`
133+
- Read context files: `active/{task-id}/`
100134
- Complete task checklist
101-
- Create output files
135+
- Update task status (CRITICAL: see Rule 7)
102136

103-
AI handoff: Any AI can take over by reading the context directory.
137+
AI handoff: Any AI can take over by reading the task directory.
104138

105139
### AI Capabilities Reference
106140

@@ -114,8 +148,11 @@ AI handoff: Any AI can take over by reading the context directory.
114148
### Detailed Documentation
115149

116150
- Collaboration Guide: `.ai-agents/README.md`
151+
- Quick Start: `.ai-agents/QUICKSTART.md`
117152
- Workflow Definitions: `.ai-agents/workflows/`
118153
- Claude Config: `.claude/README.md`
154+
- Claude Project Rules: `.claude/project-rules.md` (includes Rule 7: Task Status Management)
155+
- Claude Command Reference: `.claude/commands/`
119156
- ChatGPT Config: `.ai-agents/chatgpt/README.md`
120157
- Gemini Config: `.ai-agents/gemini/README.md`
121158

0 commit comments

Comments
 (0)