project-implementation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Implementation

项目实现

Overview

概述

Implement a project that is documented and specified in

docs/

. Work through a structured todo list, implementing ALL phases and sections in a single continuous session, running tests, committing, and updating progress tracking files after each step.

Core principles:

NEVER stop between phases. Implement ALL phases from start to finish in one continuous session. Do NOT pause after completing a phase to ask if you should continue — just continue.
NEVER ask the user questions. If you encounter ambiguity, uncertainty, or need to make a decision, make your best judgment based on the documentation and record the question/decision in
```
docs/questions.md
```
for later review. NEVER use AskUserQuestion or stop to ask for input.
Never skip tests. Never mark a task as done without verified implementation. Always commit after each completed section. Always update tracking files before moving to the next task.

实现

docs/

目录下已记录规范的项目。按照结构化的待办事项清单推进，在一个连续的会话中完成所有阶段与模块的开发，运行测试，提交代码，并在每一步完成后更新进度跟踪文件。

核心原则：

绝对不要在阶段之间停顿。 在一个连续的会话中从头至尾完成所有阶段的实现。完成一个阶段后不要暂停询问是否继续——直接推进。
绝对不要向用户提问。 如果遇到歧义、不确定的情况或需要做决策，根据现有文档做出最佳判断，并将问题/决策记录在
```
docs/questions.md
```
中供后续审核。绝对不要使用AskUserQuestion工具或停顿请求输入。
绝对不要跳过测试。 未经过验证的实现不能标记为完成。完成每个模块后必须提交代码。进入下一个任务前必须更新跟踪文件。

Questions Protocol

问题处理流程

When you encounter a question, ambiguity, or need to make a judgment call:

DO NOT stop or ask the user — make the best decision you can based on available documentation

Record it in
docs/questions.md
with the following format:

markdown

## [Phase X — Section Name]

**Q:** What is the expected behavior when X happens?
**Decision:** I chose to do Y because Z.
**Impact:** Low/Medium/High — affects [description].

Continue implementing — the user will review
```
docs/questions.md
```
after all development is complete

当遇到问题、歧义或需要做出判断时：

不要停顿或询问用户——根据现有文档做出最佳决策

将内容记录在
docs/questions.md
中，格式如下：

markdown

## [第X阶段 — 模块名称]

**问题：** 当X发生时，预期行为是什么？
**决策：** 我选择执行Y，原因是Z。
**影响：** 低/中/高 — 影响[描述]。

继续实现——用户会在所有开发完成后审核
```
docs/questions.md
```

The Process

执行流程

Phase 1: Read Project Documentation

阶段1：阅读项目文档

Read all files in
docs/
bash
```
find docs/ -type f -name '*.md' | sort
```
Read every documentation file to understand the full project scope, architecture, and requirements.
Read
docs/implementation.md
(Implementation Plan)
- If it exists → read it carefully to understand the phases, order of execution, and dependencies
- If it does NOT exist → create it from the specification files in
```
docs/
```
  :
  - Analyze all spec documents
  - Break the project into logical implementation phases (Phase 0: Setup, Phase 1: Core, Phase 2: Features, etc.)
  - Each phase should have clear deliverables and acceptance criteria
  - Write the plan to
```
docs/implementation.md
```

Read
docs/todo.md
(Task Checklist)

If it exists → read it to understand what needs to be done

If it does NOT exist → create it from

docs/implementation.md

Convert each phase into a section with checkbox items
Each item should be a single, atomic, implementable task
Use the format
```
- [ ]
```
for pending and
```
- [x]
```
for completed
Group by phase, with clear section headers

Example structure:

markdown

# Project Name — TODO

---

## Phase 0 — Setup

### Initialization
- [ ] Create `package.json`
- [ ] Create `tsconfig.json`
- [ ] Create `.gitignore`

### Build
- [ ] Install dev dependencies
- [ ] Create build config
- [ ] Validate `npm run build` works
- [ ] Validate `npm run test` works

### Directory Structure
- [ ] Create `src/` directories
- [ ] Create `__tests__/` directories

---

## Phase 1 — Core Feature

### Sub-feature A
- [ ] Implement X
- [ ] Implement Y
- [ ] Write tests for X and Y

Read
docs/implemented.md
(Implementation Log)
- If it exists → read it to understand what was already done and where to resume
- If it does NOT exist → create it with this initial content:
  markdown
```
# Implementation Log

> Auto-updated after each implementation cycle.

---
```

阅读
docs/
目录下的所有文件
bash
```
find docs/ -type f -name '*.md' | sort
```
阅读所有文档文件，全面了解项目范围、架构与需求。
阅读
docs/implementation.md
（实现计划）
- 如果文件存在 → 仔细阅读，了解实现阶段、执行顺序与依赖关系
- 如果文件不存在 → 根据
```
docs/
```
  目录下的规范文件创建该文件：
  - 分析所有规范文档
  - 将项目拆分为逻辑清晰的实现阶段（如阶段0：环境搭建，阶段1：核心功能，阶段2：扩展功能等）
  - 每个阶段需明确交付成果与验收标准
  - 将计划写入
```
docs/implementation.md
```

阅读
docs/todo.md
（任务清单）

如果文件存在 → 阅读以了解待完成任务

如果文件不存在 → 根据

docs/implementation.md

创建该文件：

将每个阶段转换为带复选框的任务项
每个任务项应为单一、可独立实现的原子任务
使用
```
- [ ]
```
表示待完成，
```
- [x]
```
表示已完成
按阶段分组，使用清晰的模块标题

示例结构：

markdown

# 项目名称 — 待办事项

---

## 阶段0 — 环境搭建

### 初始化
- [ ] 创建`package.json`
- [ ] 创建`tsconfig.json`
- [ ] 创建`.gitignore`

### 构建配置
- [ ] 安装开发依赖
- [ ] 创建构建配置
- [ ] 验证`npm run build`可正常运行
- [ ] 验证`npm run test`可正常运行

### 目录结构
- [ ] 创建`src/`目录
- [ ] 创建`__tests__/`目录

---

## 阶段1 — 核心功能

### 子功能A
- [ ] 实现X功能
- [ ] 实现Y功能
- [ ] 为X和Y编写测试用例

阅读
docs/implemented.md
（实现日志）
- 如果文件存在 → 阅读以了解已完成工作与后续起始点
- 如果文件不存在 → 创建该文件并写入初始内容：
  markdown
```
# 实现日志

> 每个实现周期后自动更新。

---
```

Phase 2: Determine Where to Resume

阶段2：确定起始点

Compare
```
docs/todo.md
```
with
```
docs/implemented.md
```
Find the first unchecked item (
```
- [ ]
```
) in
```
todo.md
```
That is the starting point for this session

对比
```
docs/todo.md
```
与
```
docs/implemented.md
```
找到
```
todo.md
```
中第一个未勾选的任务项（
```
- [ ]
```
）
该任务即为本次会话的起始点

Phase 3: Implementation Loop

阶段3：实现循环

For each unchecked section/group in

todo.md

, repeat:

针对

todo.md

中每个未勾选的模块/组，重复以下步骤：

3a. Implement

3a. 开发实现

Read the task description
Implement the minimum required to complete all items in the current section/group
Follow project conventions found in the documentation
Stay focused on the scope — no "while I'm here" changes

阅读任务描述
完成当前模块/组内所有任务项的最小必要实现
遵循文档中定义的项目规范
聚焦当前范围——不要进行“顺便”的额外修改

3b. Run Tests

3b. 运行测试

bash

undefined

bash

undefined

Run the project's test command (detect from package.json, Makefile, etc.)

运行项目的测试命令（从package.json、Makefile等文件中识别）

npm run test

or

或

bundle exec rspec

or

或

pytest

or whatever the project uses

或项目使用的其他测试命令


- All tests MUST pass before proceeding
- If tests fail, fix them before moving on
- If the section introduces new behavior, write tests for it


- 所有测试必须通过后才能推进
- 如果测试失败，修复问题后再继续
- 如果当前模块引入了新行为，为其编写测试用例

3c. Commit

3c. 提交代码

bash

git add <changed files>
git commit -m "feat: <description of what was implemented>

Co-Authored-By: Claude <noreply@anthropic.com>"

One commit per completed section/group
Use conventional commits:
```
feat:
```
,
```
fix:
```
,
```
chore:
```
,
```
refactor:
```
,
```
test:
```
Commit message in the project's language (follow existing commit style)

bash

git add <修改的文件>
git commit -m "feat: <实现内容描述>

Co-Authored-By: Claude <noreply@anthropic.com>"

每个完成的模块/组对应一次提交
使用约定式提交规范：
```
feat:
```
、
```
fix:
```
、
```
chore:
```
、
```
refactor:
```
、
```
test:
```
提交信息使用项目采用的语言（遵循现有提交风格）

3d. Update

docs/todo.md

3d. 更新

docs/todo.md

Mark all completed items as done:

markdown

- [x] Create `package.json`  ← was `- [ ]`

将所有已完成的任务标记为已完成：

markdown

- [x] 创建`package.json`  ← 原为`- [ ]`

3e. Update

docs/implemented.md

3e. 更新

docs/implemented.md

Append a summary of what was implemented:

markdown

undefined

追加本次实现的内容摘要：

markdown

undefined

Phase 0 — Setup > Initialization

阶段0 — 环境搭建 > 初始化

Created
```
package.json
```
with scope
```
@project/name
```
Created
```
tsconfig.json
```
targeting ES2022
Created
```
.gitignore
```

Commit:

abc1234

undefined

创建了带有
```
@project/name
```
作用域的
```
package.json
```
创建了目标为ES2022的
```
tsconfig.json
```
创建了
```
.gitignore
```

提交哈希：

abc1234

undefined

3f. Commit Tracking Updates and Continue

3f. 提交跟踪文件更新并继续

After updating tracking files:

Commit the tracking file updates:

bash

git add docs/todo.md docs/implemented.md docs/questions.md
git commit -m "docs: update implementation progress

Co-Authored-By: Claude <noreply@anthropic.com>"

Immediately continue to the next unchecked section — do NOT stop, do NOT ask the user, do NOT restart the process. Loop back to step 3a with the next section.

CRITICAL: Do NOT stop between phases. The entire project must be implemented in a single continuous session. Move from one section to the next without interruption until ALL items in

todo.md

are checked.

更新跟踪文件后：

提交跟踪文件的更新：

bash

git add docs/todo.md docs/implemented.md docs/questions.md
git commit -m "docs: 更新实现进度

Co-Authored-By: Claude <noreply@anthropic.com>"

立即推进到下一个未勾选的模块——不要停顿，不要询问用户，不要重启流程。回到步骤3a处理下一个模块。

关键注意事项：绝对不要在阶段之间停顿。 整个项目必须在一个连续的会话中完成实现。不间断地从一个模块推进到下一个模块，直到

todo.md

中的所有任务项都被勾选。

Phase 4: Completion

阶段4：完成收尾

When all items in

todo.md

are checked (

- [x]

Run the full test suite one final time
Update
```
docs/implemented.md
```
with a completion summary
If
```
docs/questions.md
```
has entries, inform the user to review it
Inform the user that implementation is complete

当

todo.md

中的所有任务项都被勾选（

- [x]

）时：

最后一次运行完整的测试套件
在
```
docs/implemented.md
```
中添加完成摘要
如果
```
docs/questions.md
```
中有记录，告知用户进行审核
告知用户项目实现已完成

Quick Reference

快速参考

Step	Action	Success Criteria
1. Read docs	Load all project documentation	Full understanding of scope
2. Plan	Create/read implementation.md	Clear phased plan exists
3. Todo	Create/read todo.md	Granular checklist exists
4. Resume	Find first unchecked item	Know where to start
5. Implement	Code the current section	All items in section done
6. Test	Run tests	All tests pass
7. Commit	Git commit the implementation	Clean commit history
8. Track	Update todo.md + implemented.md	Progress recorded
9. Continue	Loop to step 5 with next section	All phases completed

步骤	操作	成功标准
1. 阅读文档	加载所有项目文档	全面理解项目范围
2. 制定计划	创建/阅读implementation.md	存在清晰的分阶段计划
3. 待办清单	创建/阅读todo.md	存在细化的任务清单
4. 确定起始点	找到第一个未勾选的任务	明确开发起始位置
5. 开发实现	编写当前模块的代码	模块内所有任务完成
6. 测试	运行测试	所有测试通过
7. 提交	Git提交实现代码	提交历史清晰
8. 跟踪进度	更新todo.md与implemented.md	进度已记录
9. 继续推进	循环到步骤5处理下一个模块	所有阶段完成

Red Flags — STOP and Reassess

警示信号 — 立即停止并重新评估

Implementing without reading ALL docs first
Skipping test execution after implementation
Marking tasks done without actually implementing them
Making changes outside the scope of the current section
Committing without running tests
Not updating tracking files after each cycle
Stopping between phases to ask the user questions — save questions to
```
docs/questions.md
```
and continue
Pausing after a phase to ask "Shall I continue?" — ALWAYS continue automatically
Moving to the next section when tests are failing

NEVER STOP. NEVER ASK. Follow the process until ALL phases are complete.

未先阅读所有文档就开始实现
实现完成后跳过测试环节
未实际实现就标记任务为完成
进行超出当前模块范围的修改
未运行测试就提交代码
每个循环后未更新跟踪文件
在阶段之间停顿并向用户提问——将问题保存到
```
docs/questions.md
```
并继续
完成一个阶段后询问“是否继续？”——绝对要自动继续
测试失败时仍推进到下一个模块

绝对不要停顿。绝对不要提问。遵循流程直到所有阶段完成。

Common Rationalizations

常见借口与事实

Excuse	Reality
"This section is trivial, skip tests"	Every implementation needs test verification.
"I'll update todo.md at the end"	Update after EACH section, not after all.
"I'll do multiple sections before committing"	One commit per section keeps history clean.
"Tests aren't set up yet, skip them"	Setting up tests IS part of Phase 0.
"I remember what was done, skip reading docs"	Always re-read — context may have been cleared.
"The todo is too granular"	Granular tasks = clear progress + clean commits.
"Let me ask the user about this"	Save to `docs/questions.md` and keep going.
"Phase X is done, let me check with the user"	NEVER stop — continue to the next phase immediately.

借口	事实
“这个模块很简单，跳过测试”	任何实现都需要测试验证。
“我会在最后统一更新todo.md”	每个模块完成后都要更新，不是最后统一更新。
“我会完成多个模块后再提交”	每个模块对应一次提交可保持历史清晰。
“测试还没搭建好，先跳过”	搭建测试环境是阶段0的一部分。
“我记得已完成的内容，不用读文档”	始终要重新阅读——上下文可能已丢失。
“待办清单太细了”	细化的任务 = 清晰的进度 + 干净的提交记录。
“我来问问用户这个问题”	保存到 `docs/questions.md` 并继续推进。
“第X阶段完成了，我跟用户确认下”	绝对不要停顿——立即推进到下一个阶段。

Notes

注意事项

NEVER stop between phases — implement ALL phases in one continuous session
NEVER ask the user questions — save decisions and questions to
```
docs/questions.md
```
One section per commit — keeps commits atomic and history clean
The todo.md is the source of truth — if it's not checked, it's not done
The implemented.md is the audit log — always record what was done and the commit hash
Detect the project's tech stack from docs and existing files to use the correct test/build commands
The questions.md is for post-implementation review — the user reads it after everything is done

绝对不要在阶段之间停顿——在一个连续的会话中完成所有阶段的实现
绝对不要向用户提问——将决策与问题保存到
```
docs/questions.md
```
每个模块对应一次提交——保持提交原子化与历史清晰
todo.md是唯一的事实来源——未勾选的任务即为未完成
implemented.md是审计日志——始终记录已完成工作与提交哈希
从文档与现有文件中识别项目技术栈，以使用正确的测试/构建命令
questions.md用于实现后审核——用户会在所有工作完成后阅读该文件

project-implementation

Original

Translation

Project Implementation

项目实现

Overview

概述

Questions Protocol

问题处理流程

The Process

执行流程

Phase 1: Read Project Documentation

阶段1：阅读项目文档

Phase 2: Determine Where to Resume

阶段2：确定起始点

Phase 3: Implementation Loop

阶段3：实现循环

3a. Implement

3a. 开发实现

3b. Run Tests

3b. 运行测试

Run the project's test command (detect from package.json, Makefile, etc.)

运行项目的测试命令（从package.json、Makefile等文件中识别）

or

或

or

或

or whatever the project uses

或项目使用的其他测试命令

3c. Commit

3c. 提交代码

3d. Update docs/todo.md

3d. 更新docs/todo.md

3e. Update docs/implemented.md

3e. 更新docs/implemented.md

Phase 0 — Setup > Initialization

阶段0 — 环境搭建 > 初始化

3f. Commit Tracking Updates and Continue

3f. 提交跟踪文件更新并继续

Phase 4: Completion

阶段4：完成收尾

Quick Reference

快速参考

Red Flags — STOP and Reassess

警示信号 — 立即停止并重新评估

Common Rationalizations

常见借口与事实

Notes

注意事项

3d. Update
`docs/todo.md`

3d. 更新
`docs/todo.md`

3e. Update
`docs/implemented.md`

3e. 更新
`docs/implemented.md`