Back to Details

git-checkpoint

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Git Checkpoint (Bộ nhớ Undo không tốn token)

Git Checkpoint（无需消耗token的撤销记忆库）

Branch theo từng change (làm TRƯỚC khi bắt đầu code, ngay khi có change từ 
/opsx:new
/
/opsx:propose
)

为每个变更创建分支（开始编码前执行，在通过
/opsx:new
/
/opsx:propose
生成变更后立即执行）

Không code thẳng trên 
main
. Ngay khi 1 change được tạo (sau 
/opsx:new
hoặc 
/opsx:propose
, trước khi vào 
flutter-coding
):
  1. Kiểm tra đang ở branch nào: 
    git branch --show-current
    .
  2. Nếu đang ở 
    main
    (hoặc branch chính khác) → tạo branch mới đặt tên theo change: 
    git checkout -b change/<change-name>
    (lấy 
    <change-name>
    đúng từ tên thư mục 
    openspec/changes/<change-name>/
    ).
  3. Nếu đã đang ở đúng branch 
    change/<change-name>
    từ trước (ví dụ resume qua 
    /opsx:continue
    ở session mới) → không tạo lại, dùng luôn.
  4. Toàn bộ commit theo task (mục dưới) đều nằm trên branch này, KHÔNG merge vào 
    main
    cho đến khi 
    /opsx:archive
    chạy xong.
Khi hoàn tất change (sau bước "Hoàn tất change" bên dưới, đã archive xong):
bash
git checkout main
git merge change/<change-name>
git branch -d change/<change-name>
Chỉ merge khi 
/opsx:verify
đã pass và 
/opsx:archive
đã chạy xong - không merge nửa chừng.
Nếu đang làm dở 1 change mà cần dừng để việc khác gấp: không cần làm gì thêm, 
main
vẫn sạch vì code đang nằm trên branch riêng. Quay lại sau bằng 
git checkout change/<change-name>
+ 
/opsx:continue
.
不要直接在
main
分支上编码。在生成一个变更后（执行
/opsx:new
或
/opsx:propose
之后，进入
flutter-coding
之前）：
  1. 检查当前所在分支：
    git branch --show-current
    。
  2. 如果当前处于
    main
    分支（或其他主分支）→ 创建以变更命名的新分支：
    git checkout -b change/<change-name>
    （从
    openspec/changes/<change-name>/
    目录名中获取正确的
    <change-name>
    ）。
  3. 如果之前已处于正确的
    change/<change-name>
    分支（例如在新会话中通过
    /opsx:continue
    恢复工作）→ 无需重新创建，直接使用该分支。
  4. 所有任务相关的提交（见下方章节）都将在此分支上进行，直到
    /opsx:archive
    执行完成后才可合并到
    main
    分支    。
完成变更后（在下方“完成变更”步骤之后，已完成归档）：
bash
git checkout main
git merge change/<change-name>
git branch -d change/<change-name>
仅在
/opsx:verify
通过且
/opsx:archive
执行完成后才可合并——请勿中途合并。
**如果正在处理一个变更但需要暂停以处理紧急事务：**无需额外操作，
main
分支仍保持干净，因为代码都在独立分支上。之后可通过
git checkout change/<change-name>
+ 
/opsx:continue
恢复工作。

Commit theo từng task, và hoàn tất change khi xong hết (luồng bình thường)

按任务提交，完成所有任务后结束变更（常规流程）

Commit từng task (trong lúc 
/opsx:apply
đang chạy, sau mỗi task pass 
mcp-loop
+ 
ui-checkpoint
nếu có UI):
  1. git add -A
  2. Commit message ngắn theo task vừa xong, ví dụ 
    feat(order): thêm màn hình đặt hàng trà sữa
    .
  3. Không commit khi task đó vẫn còn lỗi từ 
    mcp-loop
    chưa pass, hoặc user chưa xác nhận UI ở 
    ui-checkpoint
    (nếu task có UI).
Checkpoint giữa chừng (tùy chọn): có thể gọi 
/opsx:sync
sau vài task để merge sớm delta spec vào spec chính, không cần chờ đến khi xong hết 
tasks.md
.
Hoàn tất change (sau khi 
/opsx:verify
pass):
  1. Đảm bảo đã commit hết các task còn lại.
  2. Gọi 
    /opsx:sync
    (nếu chưa sync lần nào) rồi 
    /opsx:archive
    để merge delta spec vào 
    openspec/specs/
    chính thức và chuyển change vào 
    changes/archive/
    . Đây là bước OpenSpec quản lý, KHÔNG tự chạy raw 
    openspec archive
    qua bash để thay thế.
  3. Commit cuối cùng ghi nhận archive (nếu OpenSpec tạo thay đổi file cần commit thêm sau archive).
按任务提交（在
/opsx:apply
执行过程中，每个通过
mcp-loop
的任务完成后提交；若涉及UI，则需在
ui-checkpoint
之后提交）：
  1. git add -A
  2. 根据刚完成的任务编写简短的提交信息，例如
    feat(order): 新增奶茶下单页面
    。
  3. 如果任务未通过
    mcp-loop
    仍存在错误，或涉及UI但用户未在
    ui-checkpoint
    确认，则请勿提交。
**中途检查点（可选）：**可在完成几个任务后调用
/opsx:sync
，提前将增量规范合并到主规范中，无需等到
tasks.md
全部完成。
完成变更（
/opsx:verify
通过后）：
  1. 确保所有剩余任务均已提交。
  2. 调用
    /opsx:sync
    （若从未同步过），然后调用
    /opsx:archive
    ，将增量规范正式合并到
    openspec/specs/
    中，并将变更移至
    changes/archive/
    。此步骤由OpenSpec管理，请勿通过bash直接执行原始的
    openspec archive
    命令替代    。
  3. 最后一次提交以记录归档操作（若归档后OpenSpec生成了需要额外提交的文件变更）。

Xử lý "Undo / Quay lại"

处理“撤销/回退”请求

Khi user nói kiểu: "Bỏ tính năng Login đi", "Quay lại lúc chưa có Cart", "Undo cái vừa làm":
  1. Không đọc lại code để tự xóa thủ công. Chạy 
    git log --oneline
    để tìm commit ngay trước khi thêm tính năng cần bỏ.
  2. Xác nhận với user (ngắn gọn) hash/commit message tìm được đúng là điểm cần quay lại chưa, tránh reset nhầm.
  3. Thực hiện:
    • Nếu muốn bỏ hẳn thay đổi chưa commit hoặc mới nhất: 
      git reset --hard <hash>
      .
    • Nếu muốn giữ lịch sử (an toàn hơn, khuyến nghị mặc định): 
      git revert <hash>
      hoặc tạo branch mới từ hash cũ thay vì 
      reset --hard
      phá lịch sử.
  4. Sau khi reset/revert, chạy lại 
    mcp-loop/SKILL.md
    một lần để xác nhận app vẫn chạy được ở trạng thái vừa quay lại.
  5. Nếu change chưa được archive (còn nằm trong 
    openspec/changes/<change-name>/
    ), xóa/hủy luôn thư mục change đó thay vì chỉnh sửa spec đã archive. Nếu change ĐÃ archive rồi (đã merge vào 
    openspec/specs/
    ), tạo 1 change mới kiểu "revert" để đảo ngược phần spec đó cho đúng quy trình OpenSpec, không sửa tay trực tiếp vào 
    specs/
    đã archive.
当用户提出类似：“移除登录功能”、“回退到还没有购物车的状态”、“撤销刚做的操作” 这类请求时：
  1. 请勿手动阅读代码进行删除。执行
    git log --oneline
    查找添加该功能之前的提交记录。
  2. 简短确认用户找到的提交哈希/提交信息是否为正确的回退点，避免误重置。
  3. 执行操作：
    • 如果想要完全丢弃未提交或最新的变更：
      git reset --hard <hash>
      。
    • 如果想要保留历史记录（更安全，推荐默认使用）：
      git revert <hash>
      ，或从旧哈希创建新分支，而非使用
      reset --hard
      破坏历史记录。
  4. 重置/撤销后，重新执行一次
    mcp-loop/SKILL.md
    ，确认应用在回退后的状态仍可正常运行。
  5. 如果变更尚未归档（仍位于
    openspec/changes/<change-name>/
    ），直接删除/取消该变更目录，而非修改已归档的规范。如果变更已归档（已合并到
    openspec/specs/
    ），则创建一个“撤销”类型的新变更，按照OpenSpec流程反转该部分规范，请勿直接手动修改已归档的
    specs/
    目录。

Lưu ý an toàn

安全注意事项

  • Mặc định ưu tiên 
    git revert
    /branch mới hơn 
    git reset --hard
    để không mất lịch sử vĩnh viễn, trừ khi user nói rõ muốn xóa hẳn.
  • Không tự động push lên remote trừ khi user yêu cầu - checkpoint là local trước.
  • Nếu working tree đang dirty (có thay đổi chưa commit ngoài luồng) trước khi reset, cảnh báo user trước khi thực hiện, tránh mất code chưa lưu ngoài ý muốn.
  • 默认优先使用
    git revert
    /新分支，而非
    git reset --hard
    ，避免永久丢失历史记录，除非用户明确要求完全删除。
  • 除非用户要求，否则请勿自动推送到远程仓库——检查点先在本地执行。
  • 如果重置前工作区存在未提交的变更（流程外的修改），请先警告用户，避免意外丢失未保存的代码。