work-tracking

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Step 1: Initialize Work Directory (If Needed)

步骤1：初始化工作目录（如需要）

Before checking for active work, ensure agent-work directory exists:

bash

if [ ! -d "agent-work" ]; then
  echo "Initializing work directory..."
  cp -r .claude/skills/work-tracking/scaffold agent-work
  echo "Work directory initialized from scaffold"
fi

What this does:

Checks if
```
agent-work/
```
directory exists
If not, copies the scaffold structure from
```
.claude/skills/work-tracking/scaffold/
```
Creates the necessary
```
bin/
```
and
```
completed/
```
subdirectories
Sets up the work tracking system ready for use

在检查是否有进行中的工作前，确保agent-work目录已存在：

bash

if [ ! -d "agent-work" ]; then
  echo "Initializing work directory..."
  cp -r .claude/skills/work-tracking/scaffold agent-work
  echo "Work directory initialized from scaffold"
fi

此操作的作用：

检查
```
agent-work/
```
目录是否存在
若不存在，则从
```
.claude/skills/work-tracking/scaffold/
```
复制脚手架结构
创建必要的
```
bin/
```
和
```
completed/
```
子目录
完成工作追踪系统的初始化，准备投入使用

Step 2: Check for Active Work

步骤2：检查进行中的工作

ALWAYS do this first before creating new work.

bash

ls agent-work/*.md 2>/dev/null

If there's an active work file:

Show it to the user
Ask: "There's an active work file: [filename]. Would you like to:
1. Continue with this work
2. Complete it first
3. Create new work file"
Wait for user response before proceeding

If no active work file, proceed to Step 4.

在开展新工作前，必须先执行此步骤。

bash

ls agent-work/*.md 2>/dev/null

如果存在活跃的工作文件：

向用户展示该文件
询问：“当前存在活跃的工作文件：[文件名]。您希望：
1. 继续此项工作
2. 先完成此项工作
3. 创建新的工作文件”
等待用户回复后再继续

如果没有活跃的工作文件，直接进入步骤4。

Step 3: Create Work File (MANDATORY)

步骤3：创建工作文件（强制要求）

You MUST run this script BEFORE writing ANY code.

bash

./agent-work/bin/work-create.sh <task_name>

在编写任何代码前，必须运行此脚本。

bash

./agent-work/bin/work-create.sh <task_name>

Task Naming Rules

任务命名规则

Use descriptive, snake_case names:

✅
```
improve_pdf_generation
```
✅
```
add_watermark_support
```
✅
```
fix_date_parsing_bug
```
✅
```
implement_resume_validator
```
❌
```
new_feature
```
❌
```
stuff
```
❌
```
update
```

使用描述性的蛇形命名法（snake_case）：

✅
```
improve_pdf_generation
```
✅
```
add_watermark_support
```
✅
```
fix_date_parsing_bug
```
✅
```
implement_resume_validator
```
❌
```
new_feature
```
❌
```
stuff
```
❌
```
update
```

What the script does:

脚本的作用：

Generates UTC timestamp automatically
Creates
```
agent-work/{timestamp}_{task_name}.md
```
Populates it with the template

Example output:

Created work file: agent-work/20251230164521_improve_pdf_generation.md

自动生成UTC时间戳
创建
```
agent-work/{timestamp}_{task_name}.md
```
文件
使用模板填充文件内容

示例输出：

Created work file: agent-work/20251230164521_improve_pdf_generation.md

Step 4: Populate Work File

步骤4：填充工作文件

Immediately after creation, populate the work file with:

Context - What problem is being solved, why it's needed
Value Proposition - What the feature achieves, acceptance criteria
Alternatives Considered - Other approaches considered and why this approach was chosen
Todos - Specific, actionable tasks with
```
[ ]
```
checkboxes
Notes - Any additional information

创建文件后立即填充以下内容：

背景 - 要解决的问题是什么，为什么需要解决
价值主张 - 该功能要实现的目标、验收标准
备选方案评估 - 考虑过的其他方案，以及选择当前方案的原因
待办事项 - 具体、可执行的任务，使用
```
[ ]
```
复选框
备注 - 任何补充信息

Example Work File:

示例工作文件：

markdown

undefined

markdown

undefined

Improve PDF Generation

优化PDF生成功能

Status: in_progress

状态：进行中

Context

背景

Current PDF generation doesn't preserve text selectable layers, making it hard for ATS systems to parse. Users report that their resumes aren't being parsed correctly.

当前PDF生成功能无法保留可选文本层，导致ATS系统难以解析。用户反馈他们的简历无法被正确识别。

Value Proposition

价值主张

PDFs must have selectable text layers
Font embedding must be verified
Metadata must be properly set
ATS systems should be able to extract all text

PDF必须包含可选文本层
必须验证字体嵌入情况
必须正确设置元数据
ATS系统应能提取所有文本内容

Alternatives considered

备选方案评估

LaTeX generation: Too complex, requires LaTeX installation
Puppeteer: Similar to Playwright but less stable
Playwright (chosen): Best text layer support, reliable, well-maintained

LaTeX生成：过于复杂，需要安装LaTeX环境
Puppeteer：与Playwright类似，但稳定性较差
Playwright（最终选择）：文本层支持最佳，可靠且维护良好

Todos

待办事项

Notes

备注

---

---

Step 5: Implement Work (Update Todos Progressively)

步骤5：执行工作（逐步更新待办事项）

⚠️ CRITICAL: Update the work file after EACH todo, not after all todos.

⚠️ 关键要求：完成每个待办事项后立即更新工作文件，而非所有事项完成后批量更新。

Wrong Approach (DO NOT DO THIS):

错误做法（禁止）：

1. Complete all 5 todos
2. Update work file once with all 5 checked

1. 完成全部5项待办事项
2. 一次性将所有5项标记为已完成

Correct Approach (DO THIS):

正确做法（必须遵守）：

1. Complete Todo 1
2. Update work file: [ ] Task 1 → [x] Task 1
3. Complete Todo 2
4. Update work file: [ ] Task 2 → [x] Task 2
5. And so on...

1. 完成待办事项1
2. 更新工作文件：将`[ ] 任务1`改为`[x] 任务1`
3. 完成待办事项2
4. 更新工作文件：将`[ ] 任务2`改为`[x] 任务2`
5. 以此类推...

Why This Matters:

为何这很重要：

If AI crashes, progress isn't lost
Maintains accurate progress tracking
Allows resumption from any point
User can see real-time progress

若AI意外中断，进度不会丢失
保持进度追踪的准确性
支持从任意节点恢复工作
用户可查看实时进度

How to Update:

更新方式：

Use the Edit tool to change

[ ]

[x]

for completed todos:

Edit: agent-work/{timestamp}_{task_name}.md
Old: - [ ] Update PDF generator to verify text layer
New: - [x] Update PDF generator to verify text layer

使用编辑工具将已完成待办事项的

[ ]

改为

[x]

：

编辑：agent-work/{timestamp}_{task_name}.md
原内容：- [ ] 更新PDF生成器以验证文本层
新内容：- [x] 更新PDF生成器以验证文本层

Step 6: Complete Work

步骤6：完成工作

When ALL todos are checked as [x], complete the work:

bash

./agent-work/bin/work-complete.sh <name>

当所有待办事项都标记为
[x]
后，执行以下操作完成工作：

bash

./agent-work/bin/work-complete.sh <name>

Examples:

示例：

bash

./agent-work/bin/work-complete.sh improve_pdf_generation
./agent-work/bin/work-complete.sh 20251230164521_improve_pdf_generation

bash

./agent-work/bin/work-complete.sh improve_pdf_generation
./agent-work/bin/work-complete.sh 20251230164521_improve_pdf_generation

What the script does:

脚本的作用：

Updates status to
```
completed ({completion_timestamp})
```
Moves file to
```
agent-work/completed/
```
directory

Example output:

Completed and moved: agent-work/completed/20251230164521_improve_pdf_generation.md

将状态更新为
```
已完成（{完成时间戳}）
```
将文件移动到
```
agent-work/completed/
```
目录

示例输出：

Completed and moved: agent-work/completed/20251230164521_improve_pdf_generation.md

Work File Locations

工作文件位置

Active work:
```
agent-work/{timestamp}_{task_name}.md
```

Completed work:

agent-work/completed/{timestamp}_{task_name}.md

进行中的工作：
```
agent-work/{timestamp}_{task_name}.md
```

已完成的工作：

agent-work/completed/{timestamp}_{task_name}.md

Enforcement Checklist

合规性检查清单

First time in project:

Initialized agent-work directory from scaffold

Before writing ANY code, verify:

Checked for active work files
Created work file using
```
work-create.sh
```
Populated Context, Value Proposition, Alternatives, Todos
Work file exists in
```
agent-work/
```
directory

While implementing:

Update work file after EACH todo completion
Use Edit tool to change
```
[ ]
```
to
```
[x]
```
Never batch todo updates

After completing all todos:

Verify ALL todos are marked
```
[x]
```
Run
```
work-complete.sh
```
to move file to completed/

首次进入项目时：

在编写任何代码前，需验证：

已检查是否存在活跃的工作文件
已使用
```
work-create.sh
```
创建工作文件
已填充背景、价值主张、备选方案、待办事项
工作文件已存在于
```
agent-work/
```
目录

执行工作过程中：

完成每个待办事项后立即更新工作文件
使用编辑工具将
```
[ ]
```
改为
```
[x]
```
绝不批量更新待办事项

所有待办事项完成后：

验证所有待办事项都已标记为
```
[x]
```
运行
```
work-complete.sh
```
将文件移动到completed/目录

Common Mistakes to Avoid

需避免的常见错误

❌ Starting to code before creating work file ✅ Always create work file first

❌ Updating all todos at once after completing all work ✅ Update each todo immediately after completion

❌ Not checking for active work files ✅ Always check first:

ls agent-work/*.md

❌ Using vague task names like "update" or "fix" ✅ Use descriptive names like "fix_date_parsing_bug"

❌ Forgetting to complete work file when done ✅ Run

work-complete.sh

to move to completed/

❌ 未创建工作文件就开始编写代码 ✅ 必须先创建工作文件

❌ 完成所有工作后批量更新待办事项 ✅ 完成每个待办事项后立即更新

❌ 未检查是否存在活跃的工作文件 ✅ 必须先执行检查：

ls agent-work/*.md

❌ 使用模糊的任务名称，如"update"或"fix" ✅ 使用描述性名称，如

fix_date_parsing_bug

❌ 完成工作后忘记归档工作文件 ✅ 运行

work-complete.sh

将文件移动到completed/目录

Example Workflow

示例工作流

User Request: "Add watermark support to PDFs"

用户需求：“为PDF添加水印支持”

Step 1: Check for active work

步骤1：检查进行中的工作

bash

ls agent-work/*.md

bash

ls agent-work/*.md

(no files found)

（未找到文件）

undefined

undefined

Step 2: Create work file

步骤2：创建工作文件

bash

./agent-work/bin/work-create.sh add_pdf_watermark_support

bash

./agent-work/bin/work-create.sh add_pdf_watermark_support

Created work file: agent-work/20251230170000_add_pdf_watermark_support.md

undefined

undefined

Step 3: Populate work file

步骤3：填充工作文件

Edit the file with context, value proposition, alternatives, todos:

markdown

undefined

编辑文件，添加背景、价值主张、备选方案、待办事项：

markdown

undefined

Todos

待办事项

Step 4: Implement first todo

步骤4：执行第一个待办事项

Write code for watermark option...

Immediately after: Update work file

Edit: agent-work/20251230170000_add_pdf_watermark_support.md
Old: - [ ] Add watermark option to PDF generator
New: - [x] Add watermark option to PDF generator

编写水印选项的代码...

完成后立即更新工作文件

编辑：agent-work/20251230170000_add_pdf_watermark_support.md
原内容：- [ ] 为PDF生成器添加水印选项
新内容：- [x] 为PDF生成器添加水印选项

Step 5: Implement second todo

步骤5：执行第二个待办事项

Write code for positioning...

Immediately after: Update work file

Edit: agent-work/20251230170000_add_pdf_watermark_support.md
Old: - [ ] Implement watermark positioning
New: - [x] Implement watermark positioning

编写水印定位的代码...

完成后立即更新工作文件

编辑：agent-work/20251230170000_add_pdf_watermark_support.md
原内容：- [ ] 实现水印定位功能
新内容：- [x] 实现水印定位功能

Step 6: Continue until all todos are [x]

步骤6：重复操作直到所有待办事项标记为

[x]

Step 7: Complete work

步骤7：完成工作

bash

./agent-work/bin/work-complete.sh add_pdf_watermark_support

bash

./agent-work/bin/work-complete.sh add_pdf_watermark_support

Completed and moved: agent-work/completed/20251230170000_add_pdf_watermark_support.md

---

---

Summary

总结

MANDATORY SEQUENCE:

First time only: Initialize agent-work directory from scaffold (Step 1)
Check for active work:
```
ls agent-work/*.md
```
(Step 2)

Create work file:

./agent-work/bin/work-create.sh <task_name>

(Step 3)

Populate work file with context, todos, etc. (Step 4)
Implement EACH todo + update work file immediately after EACH (Step 5)

Complete work:

./agent-work/bin/work-complete.sh <name>

(Step 6)

NO CODE WITHOUT A WORK FILE. NO EXCEPTIONS.

强制执行的流程：

仅首次需执行：从脚手架初始化agent-work目录（步骤1）
检查进行中的工作：
```
ls agent-work/*.md
```
（步骤2）

创建工作文件：

./agent-work/bin/work-create.sh <task_name>

（步骤3）

填充工作文件，添加背景、待办事项等内容（步骤4）
执行每个待办事项 + 完成后立即更新工作文件（步骤5）

完成工作：

./agent-work/bin/work-complete.sh <name>

（步骤6）

无工作文件则禁止编写代码。无例外。

work-tracking

Original

Translation

Step 1: Initialize Work Directory (If Needed)

步骤1：初始化工作目录（如需要）

Step 2: Check for Active Work

步骤2：检查进行中的工作

Step 3: Create Work File (MANDATORY)

步骤3：创建工作文件（强制要求）

Task Naming Rules

任务命名规则

What the script does:

脚本的作用：

Step 4: Populate Work File

步骤4：填充工作文件

Example Work File:

示例工作文件：

Improve PDF Generation

优化PDF生成功能

Status: in_progress

状态：进行中

Context

背景

Value Proposition

价值主张

Alternatives considered

备选方案评估

Todos

待办事项

Notes

备注

Step 5: Implement Work (Update Todos Progressively)

步骤5：执行工作（逐步更新待办事项）

Wrong Approach (DO NOT DO THIS):

错误做法（禁止）：

Correct Approach (DO THIS):

正确做法（必须遵守）：

Why This Matters:

为何这很重要：

How to Update:

更新方式：

Step 6: Complete Work

步骤6：完成工作

Examples:

示例：

What the script does:

脚本的作用：

Work File Locations

工作文件位置

Enforcement Checklist

合规性检查清单

Common Mistakes to Avoid

需避免的常见错误

Example Workflow

示例工作流

User Request: "Add watermark support to PDFs"

用户需求：“为PDF添加水印支持”

Step 1: Check for active work

步骤1：检查进行中的工作

(no files found)

（未找到文件）

Step 2: Create work file

步骤2：创建工作文件

Created work file: agent-work/20251230170000_add_pdf_watermark_support.md

Created work file: agent-work/20251230170000_add_pdf_watermark_support.md

Step 3: Populate work file

步骤3：填充工作文件

Todos

待办事项

Step 4: Implement first todo

步骤4：执行第一个待办事项

Step 5: Implement second todo

步骤5：执行第二个待办事项

Step 6: Continue until all todos are [x]

步骤6：重复操作直到所有待办事项标记为[x]

Step 7: Complete work

步骤7：完成工作

Completed and moved: agent-work/completed/20251230170000_add_pdf_watermark_support.md

Completed and moved: agent-work/completed/20251230170000_add_pdf_watermark_support.md

Summary

步骤6：重复操作直到所有待办事项标记为
`[x]`