AgentSkillsCN

openspec-sync-specs

将增量规范同步至主规范。当用户希望以增量规范中的变更来更新主规范，而无需保存这些变更时，可使用此技能。

SKILL.md
--- frontmatter
name: openspec-sync-specs
description: Sync delta specs từ một thay đổi vào các bản spec chính. Sử dụng khi người dùng muốn cập nhật các bản spec chính bằng các thay đổi từ một bản delta spec mà không cần lưu trữ thay đổi đó.
license: MIT
compatibility: Yêu cầu openspec CLI.
metadata:
  author: openspec
  version: "1.0"
  generatedBy: "1.0.2"

Đồng bộ các delta spec từ một thay đổi vào spec chính (main specs).

Đây là một thao tác do agent điều khiển - bạn sẽ đọc các delta spec và trực tiếp chỉnh sửa các spec chính để áp dụng các thay đổi. Điều này cho phép hợp nhất thông minh (ví dụ: thêm một kịch bản mà không cần sao chép toàn bộ yêu cầu).

Đầu vào: Tùy chọn chỉ định tên thay đổi. Nếu bỏ trống, hãy kiểm tra xem có thể suy luận từ ngữ cảnh cuộc hội thoại hay không. Nếu mơ hồ hoặc không rõ ràng, bạn PHẢI yêu cầu xem danh sách các thay đổi có sẵn.

Các bước

  1. •

    Nếu không cung cấp tên thay đổi, yêu cầu chọn

    Chạy lệnh openspec list --json để lấy danh sách các thay đổi có sẵn. Sử dụng công cụ AskUserQuestion để người dùng chọn.

    Hiển thị các thay đổi có delta spec (nằm trong thư mục specs/).

    QUAN TRỌNG: KHÔNG được đoán hoặc tự ý chọn thay đổi. Luôn để người dùng quyết định.

  2. •

    Tìm các delta spec

    Tìm các file delta spec trong openspec/changes/<name>/specs/*/spec.md.

    Mỗi file delta spec chứa các phần như:

    • •## ADDED Requirements - Các yêu cầu mới cần thêm vào.
    • •## MODIFIED Requirements - Các thay đổi đối với yêu cầu hiện có.
    • •## REMOVED Requirements - Các yêu cầu cần loại bỏ.
    • •## RENAMED Requirements - Các yêu cầu cần đổi tên (định dạng FROM: / TO:).

    Nếu không tìm thấy delta spec nào, hãy thông báo cho người dùng và dừng lại.

  3. •

    Với mỗi delta spec, áp dụng các thay đổi vào spec chính

    Mỗi capability có delta spec tại openspec/changes/<name>/specs/<capability>/spec.md:

    a. Đọc delta spec để hiểu các thay đổi dự kiến.

    b. Đọc spec chính tại openspec/specs/<capability>/spec.md (có thể chưa tồn tại).

    c. Áp dụng các thay đổi một cách thông minh:

    ADDED Requirements (Yêu cầu ĐƯỢC THÊM):

    • •Nếu yêu cầu chưa tồn tại trong spec chính → thêm nó.
    • •Nếu yêu cầu đã tồn tại → cập nhật nó để khớp (xử lý như MODIFIED ngầm định).

    MODIFIED Requirements (Yêu cầu ĐƯỢC SỬA ĐỔI):

    • •Tìm yêu cầu trong spec chính.
    • •Áp dụng các thay đổi - có thể là:
      • •Thêm các kịch bản (scenario) mới (không cần sao chép cái cũ).
      • •Sửa đổi các kịch bản hiện có.
      • •Thay đổi mô tả yêu cầu.
    • •Giữ nguyên các kịch bản/nội dung không được đề cập trong bản delta.

    REMOVED Requirements (Yêu cầu BỊ LOẠI BỎ):

    • •Xóa toàn bộ khối yêu cầu khỏi spec chính.

    RENAMED Requirements (Yêu cầu ĐƯỢC ĐỔI TÊN):

    • •Tìm yêu cầu FROM, đổi tên thành TO.

    d. Tạo spec chính mới nếu capability chưa tồn tại:

    • •Tạo file openspec/specs/<capability>/spec.md.
    • •Thêm phần Mục đích (Purpose) (có thể ngắn gọn, đánh dấu là TBD).
    • •Thêm phần Yêu cầu (Requirements) với các yêu cầu đã THÊM.
  4. •

    Hiển thị tóm tắt

    Sau khi áp dụng tất cả các thay đổi, hãy tóm tắt:

    • •Những capability nào đã được cập nhật.
    • •Những thay đổi nào đã được thực hiện (yêu cầu được thêm/sửa/xóa/đổi tên).

Tham chiếu định dạng Delta Spec

markdown
## ADDED Requirements

### Requirement: Tính năng mới
Hệ thống PHẢI làm điều gì đó mới.

#### Scenario: Trường hợp cơ bản
- **KHI (WHEN)** người dùng làm X
- **THÌ (THEN)** hệ thống thực hiện Y

## MODIFIED Requirements

### Requirement: Tính năng hiện có
#### Scenario: Kịch bản mới cần thêm vào
- **KHI (WHEN)** người dùng làm A
- **THÌ (THEN)** hệ thống thực hiện B

## REMOVED Requirements

### Requirement: Tính năng đã lỗi thời

## RENAMED Requirements

- FROM: `### Requirement: Tên cũ`
- TO: `### Requirement: Tên mới`

Nguyên tắc chính: Hợp nhất thông minh

Khác với việc hợp nhất theo lập trình, bạn có thể áp dụng các cập nhật từng phần:

  • •Để thêm một kịch bản, chỉ cần đưa kịch bản đó vào mục MODIFIED - đừng sao chép các kịch bản hiện có.
  • •Bản delta đại diện cho ý định, không phải là sự thay thế toàn bộ.
  • •Sử dụng phán đoán của bạn để hợp nhất các thay đổi một cách hợp lý.

Đầu ra khi thành công

code
## Đã đồng bộ Specs: <change-name>

Các spec chính đã cập nhật:

**<capability-1>**:
- Đã thêm yêu cầu: "Tính năng mới"
- Đã sửa đổi yêu cầu: "Tính năng hiện có" (thêm 1 kịch bản)

**<capability-2>**:
- Đã tạo file spec mới
- Đã thêm yêu cầu: "Một tính năng khác"

Các spec chính hiện đã được cập nhật. Thay đổi vẫn đang ở trạng thái hoạt động - hãy lưu trữ (archive) khi quá trình triển khai (implementation) hoàn tất.

Nguyên tắc an toàn (Guardrails)

  • •Đọc cả delta spec và spec chính trước khi thực hiện thay đổi.
  • •Giữ nguyên nội dung hiện có không được đề cập trong bản delta.
  • •Nếu điều gì đó không rõ ràng, hãy yêu cầu làm rõ.
  • •Hiển thị những gì bạn đang thay đổi trong quá trình thực hiện.
  • •Thao tác này phải có tính lũy đẳng (idempotent) - chạy hai lần sẽ cho ra cùng một kết quả.