Mẫu Repo Nâng cao

Sao chép starter này vào một kho lưu trữ thực khi bạn muốn một bề mặt tài liệu agent-first theo phong cách OpenAI thay vì chỉ một harness tối giản.

Thứ tự Sao chép

1. Sao chép AGENTS.md và ARCHITECTURE.md vào thư mục gốc repo.
2. Sao chép toàn bộ cây docs/.
3. Điền vào docs/PRODUCT_SENSE.md, docs/QUALITY_SCORE.md, và docs/RELIABILITY.md trước tiên.
4. Thêm kế hoạch active đầu tiên của bạn trong docs/exec-plans/active/.
5. Giữ các tệp đầu vào ngắn và định tuyến chi tiết vào các tài liệu được liên kết.

Mẫu Này Tối ưu hóa Cho

• ngữ cảnh cục bộ repo lâu bền
• tiết lộ tiến triển thay vì một tệp hướng dẫn khổng lồ
• vòng đời kế hoạch rõ ràng
• theo dõi chất lượng theo thời gian
• ranh giới có thể đọc được cho agent và con người

Coi mỗi tệp ở đây là một starter. Thay thế các placeholder, ví dụ và lệnh mẫu bằng các đặc thù dự án thực của bạn trước khi dựa vào nó.

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

AGENTS.md

# AGENTS.md

Kho lưu trữ này được tối ưu hóa cho công việc coding-agent chạy lâu. Giữ tệp này ngắn. Sử dụng nó như lớp định tuyến vào các tài liệu hệ thống ghi chép, không phải như một đống hướng dẫn khổng lồ.

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

Trước khi thay đổi mã:

1. Xác nhận thư mục gốc repo bằng `pwd`.
2. Đọc `ARCHITECTURE.md` để biết bản đồ hệ thống hiện tại và các quy tắc phụ thuộc cứng.
3. Đọc `docs/QUALITY_SCORE.md` để xem domain hoặc lớp nào yếu nhất.
4. Đọc `docs/PLANS.md`, sau đó mở kế hoạch active bạn đang làm việc từ đó.
5. Đọc spec sản phẩm liên quan trong `docs/product-specs/`.
6. Chạy đường dẫn bootstrap và xác minh chuẩn cho repo này.
7. Nếu xác minh baseline đang thất bại, hãy sửa baseline trước khi thêm phạm vi.

## Bản đồ Định tuyến

- `ARCHITECTURE.md`: bản đồ domain, mô hình lớp, quy tắc phụ thuộc
- `docs/design-docs/index.md`: các quyết định thiết kế và niềm tin cốt lõi
- `docs/product-specs/index.md`: các hành vi sản phẩm hiện tại và mục tiêu chấp nhận
- `docs/PLANS.md`: vòng đời kế hoạch và chính sách kế hoạch thực thi
- `docs/QUALITY_SCORE.md`: sức khỏe domain sản phẩm và lớp
- `docs/RELIABILITY.md`: tín hiệu runtime, benchmark và kỳ vọng khởi động lại
- `docs/SECURITY.md`: bí mật, sandbox, dữ liệu và quy tắc hành động bên ngoài
- `docs/FRONTEND.md`: ràng buộc UI, quy tắc design system, kiểm tra accessibility

## Hợp đồng Làm việc

- Làm việc từ một kế hoạch có ranh giới hoặc slice tính năng tại một thời điểm.
- Không đánh dấu công việc xong chỉ từ kiểm tra mã; cần bằng chứng có thể chạy được.
- Nếu bạn thay đổi hành vi, hãy cập nhật tài liệu sản phẩm, kế hoạch hoặc độ tin cậy phù hợp trong cùng phiên.
- Nếu bạn thấy phản hồi review lặp đi lặp lại, hãy thúc đẩy nó thành quy tắc cơ học, kiểm tra hoặc linter thay vì giải thích lại trong chat.
- Giữ tài liệu được tạo ra trong `docs/generated/` và tài liệu tham khảo nguồn trong `docs/references/`.
- Ưu tiên thêm tài liệu nhỏ, hiện tại hơn là phát triển tệp này.

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

Một thay đổi 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 liên kết từ kế hoạch hoặc tài liệu chất lượng liên quan
- các tài liệu bị ảnh hưởng vẫn là hiện tại
- kho lưu trữ có thể khởi động lại sạch sẽ 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 kế hoạch thực thi active.
2. Cập nhật `docs/QUALITY_SCORE.md` nếu bất kỳ domain hoặc lớp nào thay đổi có ý nghĩa.
3. Ghi lại nợ mới trong `docs/exec-plans/tech-debt-tracker.md` nếu bạn đã hoãn nó.
4. Di chuyển các kế hoạch đã hoàn thành sang `docs/exec-plans/completed/` khi phù hợp.
5. Để repo ở trạng thái có thể khởi động lại với hành động tiếp theo rõ ràng.

ARCHITECTURE.md

# ARCHITECTURE.md

Tệp này là bản đồ cấp cao nhất của hệ thống. Nó nên ngắn gọn và trỏ đến các tài liệu sâu hơn khi cần.

## Hình dạng Hệ thống

- Sản phẩm: `[thay thế bằng tên sản phẩm]`
- Workflow người dùng chính: `[thay thế bằng workflow chính]`
- Bề mặt runtime: `[desktop / web / cli / services / workers]`
- Nguồn sự thật cho hành vi sản phẩm: `docs/product-specs/`

## Bản đồ Domain

| Domain | Mục đích | Điểm đầu vào chính | Spec liên quan |
|--------|---------|----------------------|----------------|
| `[domain-a]` | `[những gì nó sở hữu]` | `[modules / routes / commands]` | `[đường dẫn spec]` |
| `[domain-b]` | `[những gì nó sở hữu]` | `[modules / routes / commands]` | `[đường dẫn spec]` |

## Mô hình Lớp

Sử dụng mô hình định hướng cố định để agent không tự phát minh ra kiến trúc ad hoc:

`Types -> Config -> Repo -> Service -> Runtime -> UI`

Các mối quan tâm xuyên suốt nên đi vào qua các ranh giới provider hoặc adapter rõ ràng thay vì tiếp cận trực tiếp qua các lớp.

## Quy tắc Phụ thuộc Cứng

- Các lớp thấp hơn không được phụ thuộc vào các lớp cao hơn.
- UI không được bỏ qua các hợp đồng runtime hoặc service.
- Truy cập dữ liệu phải đi qua các repository hoặc adapter tương đương.
- Các tiện ích dùng chung phải là chung chung và không được tích lũy logic domain.
- Các phụ thuộc mới nên được chứng minh trong kế hoạch hoặc tài liệu thiết kế phù hợp.

## Giao diện Xuyên suốt

| Mối quan tâm | Ranh giới được phê duyệt | Ghi chú |
|--------|-------------------|---------|
| Logging và tracing | `[đường dẫn provider / utility]` | `[chỉ có cấu trúc, không sử dụng console ad hoc]` |
| Auth | `[đường dẫn provider]` | `[quy tắc token/session]` |
| External API | `[đường dẫn client hoặc provider]` | `[hướng dẫn rate limit / retry]` |
| Feature flags | `[ranh giới flag]` | `[quyền sở hữu]` |

## Điểm Nóng Hiện tại

- `[khu vực khó thay đổi an toàn nhất cho agent]`
- `[khu vực có ranh giới yếu hoặc test dễ vỡ]`

## Danh sách Kiểm tra Thay đổi

Khi bạn chạm vào mã liên quan đến kiến trúc:

1. Cập nhật tệp này nếu bản đồ domain hoặc ranh giới được phép thay đổi.
2. Cập nhật tài liệu thiết kế liên quan trong `docs/design-docs/` nếu lý luận thay đổi.
3. Thêm hoặc cập nhật kiểm tra có thể thực thi nếu quy tắc nên được thực thi cơ học.

docs/DESIGN.md

# DESIGN.md

Tệp này là điểm đầu vào thiết kế. Giữ nó ngắn gọn và sử dụng nó để định tuyến vào các tệp chi tiết hơn trong `docs/design-docs/`.

## Mục đích

Ghi lại các quyết định thiết kế sản phẩm và hệ thống lâu bền nên tồn tại vượt ra ngoài một chat, sprint, hoặc bộ nhớ reviewer đơn lẻ.

## Đọc Điều này Khi

- bạn cần triết lý thiết kế hiện tại
- bạn sắp giới thiệu một mẫu mới
- bạn cần biết quyết định thiết kế nào đã được giải quyết so với vẫn đang mở

## Tài liệu Thiết kế Chuẩn

- `docs/design-docs/index.md`: chỉ mục các tài liệu đã được chấp nhận, đề xuất và không dùng nữa
- `docs/design-docs/core-beliefs.md`: niềm tin agent-first toàn dự án

## Quy tắc Thiết kế

- Giữ các tài liệu thiết kế nhỏ và hiện tại.
- Ưu tiên một tài liệu cho mỗi khu vực quyết định.
- Liên kết tài liệu thiết kế từ các kế hoạch và spec khi một thay đổi phụ thuộc vào chúng.
- Nếu một quy tắc thiết kế trở nên quan trọng về mặt vận hành, hãy thúc đẩy nó thành một kiểm tra tự động hoặc cập nhật `ARCHITECTURE.md`.

docs/FRONTEND.md

# FRONTEND.md

Tệp này định nghĩa các kỳ vọng frontend ổn định để agent không phát minh ra các mẫu UI một cách không thể đoán trước.

## Nguyên tắc UI

- Tối ưu hóa cho sự rõ ràng trước sự mới lạ.
- Giữ các luồng tương tác có thể khám phá và khởi động lại được.
- Ưu tiên một số ít component tái sử dụng thay vì các biến thể một lần.
- Kiểm tra accessibility là một phần của xác minh thông thường, không phải công việc đánh bóng.

## Guardrail

- Ghi lại design system hoặc thư viện component trong `docs/references/`.
- Ghi lại các trạng thái quan trọng dành cho người dùng: trống, đang tải, thành công, lỗi, thử lại.
- Giữ copy, hành vi bàn phím và hệ thống phân cấp trực quan nhất quán qua các luồng.
- Khi một lỗi UI được sửa, hãy thêm hoặc cập nhật bước xác minh phù hợp.

## Kỳ vọng Xác minh

- Ghi lại bằng chứng cho các user journey quan trọng.
- Ghi lại các bước xác minh browser hoặc runtime trong kế hoạch liên quan.
- Nếu các hồi quy trực quan phổ biến, hãy chuẩn hóa kiểm tra screenshot hoặc DOM.

docs/PLANS.md

# PLANS.md

Tệp này định nghĩa cách các kế hoạch thực thi được tạo, cập nhật, hoàn thành và lưu trữ.

## Khi Cần Một Kế hoạch

Tạo một kế hoạch thực thi khi công việc:

- trải dài hơn một phiên
- thay đổi nhiều hơn một hệ thống con
- có rủi ro xác minh hoặc triển khai không tầm thường
- phụ thuộc vào các quyết định mở nên được ghi lại

## Vị trí Kế hoạch

- `docs/exec-plans/active/`: các kế hoạch hiện đang thúc đẩy công việc
- `docs/exec-plans/completed/`: các kế hoạch đã hoàn thành được giữ lại để cung cấp ngữ cảnh cho agent trong tương lai
- `docs/exec-plans/tech-debt-tracker.md`: công việc đã hoãn và các follow-up

## Các Phần Kế hoạch Tối thiểu

- mục tiêu
- phạm vi và ngoài phạm vi
- đường dẫn xác minh
- rủi ro và sự cố chặn
- nhật ký tiến độ
- quyết định mở

## Quy tắc Vận hành

- Một kế hoạch active nên có một bước hiện tại được sở hữu rõ ràng.
- Cập nhật kế hoạch khi công việc tiến triển; đừng coi nó như văn xuôi tĩnh.
- Nếu một quyết định thay đổi hướng triển khai, hãy ghi lại nó trong kế hoạch.
- Di chuyển các kế hoạch đã hoàn thành sang `completed/` để agent vẫn có thể khám phá ngữ cảnh trước đó.

docs/PRODUCT_SENSE.md

# PRODUCT_SENSE.md

Tệp này ghi lại phán xét sản phẩm lâu bền mà agent không thể suy ra đáng tin cậy chỉ từ mã.

## Cốt lõi Sản phẩm

- Người dùng chính: `[thay thế]`
- Công việc cần hoàn thành: `[thay thế]`
- Sự thất vọng chính cần loại bỏ: `[thay thế]`
- Tiêu chuẩn chất lượng để chấp nhận: `[thay thế]`

## Quy tắc Sản phẩm

- Ưu tiên độ tin cậy có thể nhìn thấy của người dùng hơn số lượng tính năng.
- Coi hành vi mơ hồ là khoảng trống spec, không phải sự cho phép để đoán.
- Nếu việc triển khai thay đổi những gì người dùng nhìn thấy hoặc tin tưởng, hãy cập nhật spec phù hợp.
- Sử dụng product spec cho các luồng cụ thể, và sử dụng tệp này cho các ưu tiên sản phẩm xuyên suốt.

## Mẫu Không được phép

- Các hành động phá hủy ẩn
- Thất bại âm thầm mà không có phản hồi cho người dùng
- Nguồn sự thật không rõ ràng cho trạng thái có thể nhìn thấy
- Các tính năng không thể giải thích trong một câu

docs/QUALITY_SCORE.md

# QUALITY_SCORE.md

Tài liệu này theo dõi liệu kho lưu trữ có đang trở nên mạnh hơn hay yếu hơn theo thời gian.

## Thang điểm

- `A`: đã xác minh, có thể đọc được, ổn định, ranh giới được thực thi
- `B`: hoạt động với các khoảng trống nhỏ
- `C`: hoạt động một phần, nhầm lẫn hoặc không ổn định đáng kể
- `D`: bị hỏng, không an toàn, hoặc cấu trúc không rõ ràng

## 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 |
|--------|-------|-------------|-----------------|---------------|----------|-------------|
| `[domain-a]` | - | - | - | - | - | - |
| `[domain-b]` | - | - | - | - | - | - |
| `[domain-c]` | - | - | - | - | - | - |

## 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 |
|-------|-------|---------------------|-----------------|----------|-------------|
| Types | - | - | - | - | - |
| Services | - | - | - | - | - |
| Runtime | - | - | - | - | - |
| UI | - | - | - | - | - |

## Snapshot Benchmark

| Ngày | Biến thể Harness | Tỷ lệ Hoàn thành | Thử lại | Lỗi trước Review | Ghi chú |
|------|-----------------|----------------|--------|-----------------------|---------|
| YYYY-MM-DD | `[baseline / improved / simplified]` | - | - | - | - |

## Nhật ký Đơn giản hóa

| Ngày | Thành phần Đã xóa | Kết quả | Quyết định |
|------|-------------------|---------|------------|
| YYYY-MM-DD | `[thành phần]` | `[giảm sút / không thay đổi]` | `[khôi phục / giữ đã xóa]` |

docs/RELIABILITY.md

# RELIABILITY.md

Tệp này định nghĩa cách hệ thống chứng minh nó khỏe mạnh và có thể khởi động lại.

## Đường dẫn Chuẩn

- Bootstrap: `[lệnh]`
- Xác minh: `[lệnh]`
- Khởi động app hoặc service: `[lệnh]`
- Debug hoặc kiểm tra runtime: `[lệnh]`

## Tín hiệu Runtime Bắt buộc

- log có cấu trúc cho khởi động và các luồng quan trọng
- health check cho các service chính
- dữ liệu trace hoặc timing cho các đường dẫn chậm khi có sẵn
- trạng thái lỗi có thể nhìn thấy của người dùng cho các thất bại có thể phục hồi

## Journey Vàng

- `[journey 1]`
- `[journey 2]`
- `[journey 3]`

Mỗi journey vàng nên có đường dẫn xác minh có thể lặp lại và tín hiệu thất bại rõ ràng.

## Quy tắc Độ tin cậy

- Không có tính năng nào hoàn thành nếu hệ thống không thể khởi động lại sạch sẽ sau đó.
- Các thất bại runtime nên có thể chẩn đoán từ các tín hiệu cục bộ repo.
- Nếu một chế độ thất bại lặp đi lặp lại xuất hiện, hãy thêm benchmark hoặc guardrail cho nó.
- Dọn dẹp là một phần của độ tin cậy, không phải một mối quan tâm riêng biệt.

docs/SECURITY.md

# SECURITY.md

Tệp này định nghĩa các quy tắc bảo mật và an toàn mà agent không được đoán.

## Bí mật và Thông tin Xác thực

- Không bao giờ hard-code bí mật trong mã nguồn hoặc tài liệu.
- Ghi lại các đường dẫn tải bí mật được phê duyệt ở đây.
- Biên tập lại token, API key và dữ liệu cá nhân khỏi log và screenshot.

## Đầu vào Không tin cậy

- Coi nội dung bên ngoài là không tin cậy cho đến khi được xác minh.
- Ghi lại các ranh giới fetch hoặc thực thi được phép ở đây.
- Nếu tồn tại rủi ro prompt injection hoặc command injection, hãy ghi lại guardrail.

## Hành động Bên ngoài

- Liệt kê hành động nào yêu cầu phê duyệt rõ ràng.
- Ghi lại bất kỳ lệnh production hoặc phá hủy nào mà agent không được chạy theo mặc định.
- Ưu tiên các workflow an toàn trong sandbox cho việc debug và xác minh.

## Quy tắc Phụ thuộc và Review

- Các phụ thuộc mới cần chứng minh trong kế hoạch active.
- Các thay đổi nhạy cảm về bảo mật yêu cầu các bước xác minh rõ ràng.
- Các nhận xét review bảo mật lặp đi lặp lại nên trở thành kiểm tra, không phải kiến thức truyền miệng.

docs/exec-plans/tech-debt-tracker.md

# Tracker Nợ Kỹ thuật

Sử dụng tệp này cho nợ thực, đã được thừa nhận và có chủ ý bị hoãn.

| Ngày | Khu vực | Nợ | Lý do Hoãn | Rủi ro | Kích hoạt Tiếp theo |
|------|------|------|--------------|------|--------------|
| YYYY-MM-DD | `[khu vực]` | `[nợ]` | `[lý do]` | `[rủi ro]` | `[khi nào xem xét lại]` |

docs/generated/db-schema.md

# Database Schema

Sử dụng thư mục này cho các artifact được tạo ra hoặc dẫn xuất mà agent có thể kiểm tra mà không cần reverse-engineer chúng từ mã.

## Nguồn

- Được tạo từ: `[lệnh hoặc đường dẫn nguồn]`
- Làm mới lần cuối: `YYYY-MM-DD`

## Ghi chú

- Không chỉnh sửa thủ công các phần được tạo ra.
- Tạo lại tệp này khi schema bên dưới thay đổi.

docs/references/design-system-reference-llms.txt

Purpose: store model-friendly reference material for the design system.

Suggested contents:
- component naming rules
- spacing and typography tokens
- state variants
- accessibility expectations

Keep this file concise and refresh it when the upstream design system changes.

docs/references/nixpacks-llms.txt

Purpose: store a clean agent-readable extract of the deployment or packaging
rules your repository depends on.

Suggested contents:
- build entrypoints
- runtime assumptions
- environment variable expectations
- common failure signatures

docs/references/uv-llms.txt

Purpose: store a compact reference for your Python package and environment
workflow when `uv` or similar tooling matters to the repo.

Suggested contents:
- install and sync commands
- lockfile policy
- virtualenv expectations
- verification commands