Tài liệu Tham khảo Tiếng Việt

English Version → | 中文版本 →

Các ghi chú này giải thích cách sử dụng các mẫu như một harness làm việc thực thụ thay vì một đống tệp rời rạc.

Ghi chú Tham khảo

• method-map.md: ánh xạ các chế độ lỗi chạy lâu phổ biến sang artifact hoặc chính sách giải quyết chúng đầu tiên
• initializer-agent-playbook.md: những gì initializer nên để lại trước khi công việc tính năng bắt đầu
• coding-agent-startup-flow.md: luồng bắt đầu phiên cố định cho các lần chạy coding sau
• prompt-calibration.md: cách giữ cho hướng dẫn gốc sắc nét mà không làm chúng phình to và dễ vỡ

Thứ tự Đọc Đề nghị

1. method-map.md
2. initializer-agent-playbook.md
3. coding-agent-startup-flow.md
4. prompt-calibration.md

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

coding-agent-startup-flow.md

# Luồng Khởi động Coding Agent

Sử dụng cái này ở đầu mỗi phiên sau khi khởi tạo hoàn thành.

## Mẫu Khởi động Cố định

1. Chạy `pwd` và xác nhận thư mục gốc kho lưu trữ.
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. Chạy một đường dẫn smoke hoặc end-to-end baseline.
7. Nếu baseline bị hỏng, hãy sửa điều đó trước.
8. Chọn tính năng chưa hoàn thành có mức ưu tiên cao nhất.
9. Chỉ làm việc trên tính năng đó cho đến khi nó được xác minh hoặc bị chặn rõ ràng.

## Tại sao Thứ tự này Quan trọng

- `pwd` ngăn chặn việc vô tình làm việc trong thư mục sai.
- các tệp tiến độ và tính năng khôi phục trạng thái lâu bền trước khi bắt đầu chỉnh sửa mới.
- các commit gần đây giải thích những gì đã thay đổi gần đây nhất.
- `init.sh` chuẩn hóa khởi động thay vì dựa vào bộ nhớ.
- xác minh baseline bắt các trạng thái khởi đầu bị hỏng trước khi công việc mới che giấu chúng.

## Gương Cuối Phiên

Cùng một phiên nên kết thúc bằng cách:

1. ghi lại tiến độ
2. cập nhật trạng thái tính năng
3. viết bàn giao nếu cần
4. commit công việc an toàn
5. để lại đường dẫn khởi động lại sạch sẽ

initializer-agent-playbook.md

# Playbook Initializer Agent

Sử dụng playbook này cho phiên nghiêm túc đầu tiên trong một kho lưu trữ, trước khi công việc tính năng tăng dần bắt đầu.

## Mục tiêu

Tạo ra một bề mặt vận hành ổn định để các phiên sau có thể triển khai hành vi mà không cần phải suy ra lại các lệnh khởi động, trạng thái hiện tại, hoặc ranh giới tác vụ.

## Kết quả Đầu ra Bắt buộc

Initializer nên để lại ít nhất các artifact này:

- một tệp hướng dẫn gốc như `AGENTS.md` hoặc `CLAUDE.md`
- một bề mặt tính năng có thể đọc bởi máy như `feature_list.json`
- một artifact tiến độ lâu bền như `claude-progress.md`
- một helper khởi động chuẩn như `init.sh`
- một commit cơ sở an toàn ban đầu ghi lại scaffold cơ sở

## Danh sách Kiểm tra

1. Định nghĩa đường dẫn khởi động chuẩn.
2. Định nghĩa đường dẫn xác minh chuẩn.
3. Tạo nhật ký tiến độ và ghi lại trạng thái khởi đầu.
4. Phân chia công việc thành các tính năng rõ ràng với trạng thái.
5. Tạo commit baseline sạch đầu tiên.

## Bài kiểm tra Thành công

Một phiên mới không có ngữ cảnh chat trước đó nên có thể trả lời:

- kho lưu trữ này làm gì
- cách khởi động nó
- cách xác minh nó
- những gì chưa hoàn thành
- bước tốt nhất tiếp theo là gì

method-map.md

# Bản đồ Phương pháp

Bảng này ánh xạ các chế độ lỗi coding-agent chạy lâu phổ biến nhất sang artifact hoặc quy tắc vận hành thường sửa chúng đầu tiên.

| Chế độ lỗi | Trông như thế nào trong thực tế | Sửa chữa chính | Artifact hỗ trợ |
| --- | --- | --- | --- |
| Nhầm lẫn cold-start | Một phiên mới dành hầu hết thời gian để khám phá lại cài đặt và trạng thái | Biến kho lưu trữ thành hệ thống ghi chép | `claude-progress.md` |
| Phình phạm vi | Agent bắt đầu nhiều tính năng và không hoàn thành sạch cái nào | Giới hạn phạm vi active | `feature_list.json` |
| Hoàn thành sớm | Agent tuyên bố xong sau khi chỉnh sửa mã nhưng trước khi có bằng chứng có thể chạy | Ràng buộc hoàn thành với bằng chứng | `clean-state-checklist.md` |
| Khởi động dễ vỡ | Mỗi phiên học lại cách khởi động dự án | Chuẩn hóa cài đặt và xác minh | `init.sh` |
| Bàn giao yếu | Phiên tiếp theo không thể biết những gì đã được xác minh, bị hỏng, hoặc là tiếp theo | Kết thúc với bàn giao rõ ràng | `session-handoff.md` |
| Review chủ quan | Chất lượng review phụ thuộc vào sở thích hoặc trí nhớ | Tính điểm đầu ra bằng các hạng mục cố định | `evaluator-rubric.md` |

## Nguyên tắc Vận hành

Thêm artifact nhỏ nhất giải quyết trực tiếp chế độ lỗi đã quan sát. Tránh giải quyết mọi vấn đề độ tin cậy bằng cách đổ thêm văn bản vào một tệp hướng dẫn toàn cục.

prompt-calibration.md

# Hiệu chỉnh Prompt

Hướng dẫn gốc nên định nghĩa khung vận hành, không phải mọi nước đi có thể.

## Giữ trong Tệp Gốc

- mục đích và phạm vi kho lưu trữ
- đường dẫn khởi động
- đường dẫn xác minh
- các ràng buộc không thể thương lượng
- các artifact trạng thái bắt buộc
- quy tắc cuối phiên

## Chuyển Ra Khỏi Tệp Gốc

- các edge case lịch sử dài
- chi tiết triển khai cụ thể theo chủ đề
- ghi chú kiến trúc cục bộ thuộc về gần mã
- các ví dụ chỉ áp dụng cho một hệ thống con

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

Tệp gốc nên giúp một phiên mới định hướng nhanh chóng. Nếu tệp đang trở thành bãi rác cho mọi lỗi trong quá khứ, hãy chia chi tiết thành các tài liệu nhỏ hơn và liên kết đến chúng thay thế.