Thư viện Mẫu

English Version → | 中文版本 →

Các mẫu harness sẵn sàng sử dụng cho các dự án agent.

Mẫu Có sẵn

• AGENTS.md — Tệp hướng dẫn agent chuẩn
• CLAUDE.md — Biến thể dành cho Claude Code
• claude-progress.md — Nhật ký tiến độ phiên
• clean-state-checklist.md — Danh sách kiểm tra trạng thái sạch khi thoát phiên
• evaluator-rubric.md — Rubric tính điểm evaluator
• quality-document.md — Mẫu tài liệu chất lượng
• session-handoff.md — Mẫu bàn giao phiên ngắn gọn

Code và tài liệu đi kèm

AGENTS.md

# AGENTS.md

Kho lưu trữ này được thiết kế cho công việc coding-agent chạy lâu. Mục tiêu không phải là tối đa hóa đầu ra mã thô. Mục tiêu là để lại repo ở trạng thái mà phiên tiếp theo có thể tiếp tục mà không cần đoán.

## Quy trình Khởi động

Trước khi viết mã:

1. Xác nhận thư mục làm việc bằng `pwd`.
2. Đọc `claude-progress.md` để biết trạng thái đã xác minh mới nhất và bước tiếp theo.
3. Đọc `feature_list.json` và chọn tính năng chưa hoàn thành có mức ưu tiên cao nhất.
4. Xem lại các commit gần đây bằng `git log --oneline -5`.
5. Chạy `./init.sh`.
6. Chạy xác minh smoke hoặc end-to-end cần thiết trước khi bắt đầu công việc mới.

Nếu xác minh baseline đã thất bại, hãy sửa điều đó trước. Không chồng công việc tính năng mới lên trên trạng thái khởi đầu bị hỏng.

## Quy tắc Làm việc

- Làm việc trên một tính năng tại một thời điểm.
- Không đánh dấu tính năng hoàn thành chỉ vì mã đã được thêm vào.
- Giữ các thay đổi trong phạm vi tính năng đã chọn trừ khi có sự cố chặn cần sửa hỗ trợ hẹp.
- Không thay đổi ngầm các quy tắc xác minh trong khi triển khai.
- Ưu tiên các artifact repo lâu bền hơn tóm tắt chat.

## Artifact Bắt buộc

- `feature_list.json`: nguồn sự thật cho trạng thái tính năng
- `claude-progress.md`: nhật ký phiên và trạng thái đã xác minh hiện tại
- `init.sh`: đường dẫn khởi động và xác minh chuẩn
- `session-handoff.md`: bàn giao ngắn gọn tùy chọn cho các phiên lớn hơn

## Định nghĩa Hoàn thành

Một tính năng chỉ xong khi tất cả những điều sau đây là đúng:

- hành vi mục tiêu đã được triển khai
- xác minh cần thiết đã thực sự chạy
- bằng chứng được ghi lại trong `feature_list.json` hoặc `claude-progress.md`
- kho lưu trữ vẫn có thể khởi động lại từ đường dẫn khởi động chuẩn

## Cuối Phiên

Trước khi kết thúc phiên:

1. Cập nhật `claude-progress.md`.
2. Cập nhật `feature_list.json`.
3. Ghi lại bất kỳ rủi ro hoặc sự cố chặn chưa được giải quyết nào.
4. Commit với thông điệp mô tả khi công việc ở trạng thái an toàn.
5. Để repo đủ sạch để phiên tiếp theo có thể chạy `./init.sh` ngay lập tức.

CLAUDE.md

# CLAUDE.md

Bạn đang làm việc trong một kho lưu trữ được thiết kế cho công việc triển khai chạy lâu. Ưu tiên hoàn thành đáng tin cậy, tính liên tục qua các phiên, và xác minh rõ ràng hơn tốc độ.

## Vòng lặp Vận hành

Ở đầu mỗi phiên:

1. Chạy `pwd` và xác nhận bạn đang ở trong thư mục gốc kho lưu trữ dự kiến.
2. Đọc `claude-progress.md`.
3. Đọc `feature_list.json`.
4. Xem lại các commit gần đây bằng `git log --oneline -5`.
5. Chạy `./init.sh`.
6. Kiểm tra xem đường dẫn smoke hoặc end-to-end baseline có đã bị hỏng chưa.

Sau đó chọn chính xác một tính năng chưa hoàn thành và chỉ làm việc trên tính năng đó cho đến khi bạn xác minh nó hoặc ghi lại lý do tại sao nó bị chặn.

## Quy tắc

- Một tính năng active tại một thời điểm.
- Không tuyên bố hoàn thành mà không có bằng chứng có thể chạy được.
- Không viết lại feature list để ẩn công việc chưa hoàn thành.
- Không xóa hoặc làm yếu các test chỉ để tác vụ có vẻ hoàn thành.
- Sử dụng các artifact kho lưu trữ như hệ thống ghi chép.

## Tệp Bắt buộc

- `feature_list.json`
- `claude-progress.md`
- `init.sh`
- `session-handoff.md` khi bàn giao ngắn gọn hữu ích

## Cổng Hoàn thành

Một tính năng chỉ có thể chuyển sang `passing` sau khi xác minh cần thiết thành công và kết quả được ghi lại.

## Trước khi Bạn Dừng

1. Cập nhật nhật ký tiến độ.
2. Cập nhật trạng thái tính năng.
3. Ghi lại những gì vẫn bị hỏng hoặc chưa được xác minh.
4. Commit khi kho lưu trữ an toàn để tiếp tục.
5. Để lại đường dẫn khởi động lại sạch sẽ cho phiên tiếp theo.

claude-progress.md

# Nhật ký Tiến độ

## Trạng thái Đã xác minh Hiện tại

- Thư mục gốc kho lưu trữ:
- Đường dẫn khởi động chuẩn:
- Đường dẫn xác minh chuẩn:
- Tính năng chưa hoàn thành có mức ưu tiên cao nhất hiện tại:
- Sự cố chặn hiện tại:

## Nhật ký Phiên

### Phiên 001

- Ngày:
- Mục tiêu:
- Đã hoàn thành:
- Xác minh đã chạy:
- Bằng chứng đã ghi lại:
- Commit:
- Tệp hoặc artifact đã cập nhật:
- Rủi ro đã biết hoặc vấn đề chưa được giải quyết:
- Bước tốt nhất tiếp theo:

### Phiên 002

- Ngày:
- Mục tiêu:
- Đã hoàn thành:
- Xác minh đã chạy:
- Bằng chứng đã ghi lại:
- Commit:
- Tệp hoặc artifact đã cập nhật:
- Rủi ro đã biết hoặc vấn đề chưa được giải quyết:
- Bước tốt nhất tiếp theo:

clean-state-checklist.md

# Danh sách Kiểm tra Trạng thái Sạch

- [ ] Đường dẫn khởi động chuẩn vẫn hoạt động.
- [ ] Đường dẫn xác minh chuẩn vẫn chạy được.
- [ ] Tiến độ hiện tại được ghi lại trong nhật ký tiến độ.
- [ ] Trạng thái tính năng phản ánh những gì thực sự đang vượt qua so với chưa được xác minh.
- [ ] Không có bước làm dở nào bị bỏ lại mà không được ghi lại.
- [ ] Phiên tiếp theo có thể tiếp tục mà không cần sửa chữa thủ công.

evaluator-rubric.md

# Rubric Evaluator

Sử dụng rubric này sau khi triển khai và trước khi chấp nhận cuối cùng.

| Hạng mục | Câu hỏi | Điểm (0-2) | Ghi chú |
| --- | --- | --- | --- |
| Tính đúng đắn | Hành vi đã triển khai có khớp với tính năng được yêu cầu không? |  |  |
| Xác minh | Các kiểm tra bắt buộc có thực sự chạy, với bằng chứng không? |  |  |
| Kỷ luật phạm vi | Phiên có ở trong phạm vi tính năng đã chọn không? |  |  |
| Độ tin cậy | Kết quả có tồn tại qua khởi động lại hoặc chạy lại mà không cần sửa chữa không? |  |  |
| Khả năng bảo trì | Mã và tài liệu có đủ rõ ràng cho phiên tiếp theo không? |  |  |
| Sẵn sàng bàn giao | Một phiên mới có thể tiếp tục công việc chỉ từ các artifact repo không? |  |  |

## Kết luận

- Chấp nhận
- Sửa đổi
- Chặn

## Hành động Tiếp theo Bắt buộc

- Bằng chứng còn thiếu:
- Sửa chữa bắt buộc:
- Kích hoạt review tiếp theo:

feature_list.json

{
  "project": "replace-with-project-name",
  "last_updated": "YYYY-MM-DD",
  "rules": {
    "single_active_feature": true,
    "passing_requires_evidence": true,
    "do_not_skip_verification": true
  },
  "status_legend": {
    "not_started": "Work has not begun.",
    "in_progress": "The feature is the current active task.",
    "blocked": "Work cannot continue until a documented blocker is resolved.",
    "passing": "Required verification has passed and evidence is recorded."
  },
  "features": [
    {
      "id": "chat-001",
      "priority": 1,
      "area": "chat",
      "title": "Create a new conversation",
      "user_visible_behavior": "A user can click New Chat and see a fresh empty conversation.",
      "status": "not_started",
      "verification": [
        "Open the app.",
        "Click New Chat.",
        "Verify a new conversation appears in the sidebar.",
        "Verify the main panel shows an empty conversation state."
      ],
      "evidence": [],
      "notes": ""
    },
    {
      "id": "chat-002",
      "priority": 2,
      "area": "chat",
      "title": "Send a message in the current conversation",
      "user_visible_behavior": "A user can submit a message and see it appear in the active thread.",
      "status": "not_started",
      "verification": [
        "Open an existing conversation.",
        "Type a message into the input.",
        "Submit the message.",
        "Verify the new message appears in the thread."
      ],
      "evidence": [],
      "notes": ""
    },
    {
      "id": "chat-003",
      "priority": 3,
      "area": "chat",
      "title": "Persist the active conversation list",
      "user_visible_behavior": "A user sees previously created conversations after restarting the app.",
      "status": "not_started",
      "verification": [
        "Create two conversations.",
        "Restart the app.",
        "Verify both conversations still appear in the sidebar."
      ],
      "evidence": [],
      "notes": ""
    }
  ]
}

init.sh

#!/usr/bin/env bash

set -euo pipefail

ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
cd "$ROOT_DIR"

# Replace these commands with the correct commands for your repository.
INSTALL_CMD=(npm install)
VERIFY_CMD=(npm test)
START_CMD=(npm run dev)

echo "==> Working directory: $PWD"
echo "==> Syncing dependencies"
"${INSTALL_CMD[@]}"

echo "==> Running baseline verification"
"${VERIFY_CMD[@]}"

echo "==> Startup command"
printf '    %q' "${START_CMD[@]}"
printf '\n'

if [ "${RUN_START_COMMAND:-0}" = "1" ]; then
  echo "==> Starting the app"
  exec "${START_CMD[@]}"
fi

echo "Set RUN_START_COMMAND=1 if you want init.sh to launch the app directly."

quality-document.md

# Tài liệu Chất lượng

Một snapshot chất lượng cho mỗi domain sản phẩm và lớp kiến trúc. Cả agent và con người đều có thể sử dụng tài liệu này để nhanh chóng hiểu nơi nào codebase mạnh và nơi nào cần cải thiện.

**Tần suất cập nhật:** Sau mỗi phiên quan trọng, hoặc trước khi bắt đầu giai đoạn công việc mới.

**Thang điểm:**

- **A**: Tất cả xác minh đang vượt qua, kiến trúc sạch, agent có thể đọc được, test ổn định
- **B**: Xác minh đang vượt qua, hầu hết sạch, thiếu nhỏ về khả năng đọc hoặc độ phủ test
- **C**: Hoạt động một phần, có khoảng trống đã biết, một số khu vực mã khó cho agent hiểu
- **D**: Không hoạt động, hoặc có vấn đề cấu trúc lớn

---

## Domain Sản phẩm

| Domain | Điểm | Xác minh | Khả năng đọc của Agent | Độ ổn định Test | Khoảng trống chính | Cập nhật lần cuối |
|--------|-------|-------------|-----------------|---------------|----------|-------------|
| Import Tài liệu | - | - | - | - | - | - |
| Quản lý Tài liệu | - | - | - | - | - | - |
| Indexing Tài liệu | - | - | - | - | - | - |
| Luồng Q&A | - | - | - | - | - | - |
| Câu trả lời có Grounding | - | - | - | - | - | - |

## Lớp Kiến trúc

| Lớp | Điểm | Thực thi Ranh giới | Khả năng đọc của Agent | Khoảng trống chính | Cập nhật lần cuối |
|-------|-------|---------------------|-----------------|----------|-------------|
| Main Process | - | - | - | - | - |
| Preload | - | - | - | - | - |
| Renderer | - | - | - | - | - |
| Services | - | - | - | - | - |

## Lịch sử Thay đổi

### YYYY-MM-DD

- Thay đổi:
- Domain được nâng cấp:
- Domain bị hạ cấp:
- Khoảng trống mới được xác định:
- Khoảng trống đã đóng:

session-handoff.md

# Bàn giao Phiên

## Đang Hoạt động Hiện tại

- Những gì đang hoạt động:
- Xác minh nào thực sự đã chạy:

## Thay đổi Trong Phiên này

- Mã hoặc hành vi đã thêm:
- Thay đổi cơ sở hạ tầng hoặc harness:

## Bị Hỏng hoặc Chưa được Xác minh

- Lỗi đã biết:
- Đường dẫn chưa được xác minh:
- Rủi ro cho phiên tiếp theo:

## Bước Tốt nhất Tiếp theo

- Tính năng chưa hoàn thành có mức ưu tiên cao nhất:
- Tại sao đây là tính năng tiếp theo:
- Điều gì được tính là vượt qua:
- Điều gì không được thay đổi trong bước đó:

## Lệnh

- Khởi động:
- Xác minh:
- Lệnh debug tập trung: