Thư viện SOP

English Version → | 中文版本 →

Các quy trình vận hành chuẩn từng bước để thiết lập và vận hành harness.

SOP Có sẵn

• layered-domain-architecture.md: thiết lập kiến trúc domain phân lớp để agent không vi phạm ranh giới
• encode-knowledge-into-repo.md: di chuyển kiến thức ẩn từ chat, tài liệu và bộ nhớ vào các tệp cục bộ repo
• observability-feedback-loop.md: cung cấp cho agent log, metrics, trace và vòng lặp debug có thể lặp lại
• chrome-devtools-validation-loop.md: sử dụng tự động hóa browser và snapshot để xác minh hành vi UI cho đến khi sạch

Cách Sử dụng Chúng

1. Chọn SOP phù hợp với điểm nghẽn hiện tại của bạn.
2. Sử dụng danh sách kiểm tra để thiết lập các artifact hoặc công cụ còn thiếu.
3. Mã hóa các quy tắc kết quả vào các tài liệu repo-template/ đã sao chép của bạn.
4. Chuyển đổi các nhận xét review lặp đi lặp lại thành kiểm tra, script hoặc guardrail.

Những điều này không phải để được tuân theo mù quáng. Chúng được thiết kế để làm cho harness có thể đọc được, có thể thực thi và có thể lặp lại hơn.

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

chrome-devtools-validation-loop.md

# SOP: Vòng lặp Xác minh Chrome DevTools

Sử dụng SOP này khi công việc UI phụ thuộc vào tương tác runtime thực tế và screenshot, trạng thái DOM và đầu ra console quan trọng hơn chỉ kiểm tra mã.

## Mục tiêu

Biến xác minh UI thành một vòng lặp tương tác có thể lặp lại mà agent có thể chạy cho đến khi journey sạch sẽ.

## Vòng lặp Cốt lõi

1. Chọn trang mục tiêu hoặc phiên bản ứng dụng.
2. Xóa noise console lỗi thời.
3. Chụp trạng thái TRƯỚC.
4. Kích hoạt đường dẫn UI.
5. Quan sát các sự kiện runtime trong khi tương tác.
6. Chụp trạng thái SAU.
7. Áp dụng sửa chữa và khởi động lại ứng dụng nếu cần.
8. Chạy lại xác minh cho đến khi journey sạch sẽ.

## Đầu vào Bắt buộc

- một lệnh khởi động ổn định
- một UI journey có thể tái tạo
- một cách để snapshot DOM, console hoặc screenshot
- một quy tắc cho những gì được tính là "sạch sẽ"

## SOP Thực thi

1. Viết journey mục tiêu trong kế hoạch active.
2. Định nghĩa thành công theo các thuật ngữ có thể quan sát: văn bản hiện diện, nút được bật, lỗi biến mất, console sạch, yêu cầu thành công.
3. Snapshot trạng thái ban đầu trước khi tương tác.
4. Kích hoạt chính xác một đường dẫn mỗi lần.
5. Ghi lại các sự kiện runtime, thay đổi DOM và đầu ra có thể nhìn thấy.
6. Nếu journey thất bại, hãy sửa lớp chịu trách nhiệm nhỏ nhất và khởi động lại.
7. Chạy lại cùng đường dẫn và so sánh bằng chứng TRƯỚC/SAU.

## Tiêu chí Sạch sẽ

- trạng thái có thể nhìn thấy dự định là hiện diện
- các lỗi không mong đợi vắng mặt
- noise console được hiểu hoặc đã xóa
- chạy lại cùng đường dẫn cho cùng kết quả

## Artifact Repo Cần Cập nhật

- kế hoạch thực thi active
- `docs/RELIABILITY.md` nếu journey trở thành một golden path
- product spec nếu hành vi có thể nhìn thấy thay đổi

encode-knowledge-into-repo.md

# SOP: Mã hóa Kiến thức Ẩn vào Repo

Sử dụng SOP này khi ngữ cảnh quan trọng vẫn còn trong Google Docs, luồng chat, ticket hoặc trong đầu của mọi người.

## Mục tiêu

Làm cho kiến thức ẩn với agent có thể khám phá được trong codebase để một phiên mới có thể hành động dựa trên nó mà không cần dựa vào hội thoại trước.

## Tín hiệu Kích hoạt

- Agent tiếp tục hỏi cách hệ thống hoạt động.
- Con người nói "chúng tôi đã quyết định điều này trong Slack" hoặc "làm theo những gì X nói tuần trước."
- Các review tham chiếu đến các quy tắc sản phẩm hoặc bảo mật không được viết trong repo.
- Các phiên mới lặp lại công việc khám phá đáng lẽ đã được giải quyết.

## SOP Thực thi

1. Liệt kê các nguồn kiến thức ẩn: tài liệu, chat, quy tắc team mặc nhiên, quyết định bằng miệng.
2. Cho mỗi nguồn, hỏi: đây là kiến trúc, hành vi sản phẩm, chính sách bảo mật, kỳ vọng độ tin cậy, ngữ cảnh kế hoạch hay tài liệu tham khảo?
3. Mã hóa nó vào artifact repo phù hợp:
   - kiến trúc -> `ARCHITECTURE.md`
   - hành vi sản phẩm -> `docs/product-specs/`
   - lý luận thiết kế -> `docs/design-docs/`
   - trạng thái thực thi -> `docs/exec-plans/`
   - tài liệu tham khảo bên ngoài lặp đi lặp lại -> `docs/references/`
   - kỳ vọng chất lượng hoặc độ tin cậy -> `docs/QUALITY_SCORE.md` hoặc `docs/RELIABILITY.md`
4. Thay thế các phát biểu mơ hồ bằng cách diễn đạt hữu ích về mặt vận hành.
5. Xóa hoặc không dùng các bản sao lỗi thời để repo giữ một sự thật có thể khám phá.

## Quy tắc Mã hóa Tốt

- Viết cho khả năng khám phá, không phải cho sự hoàn chỉnh về văn học.
- Ưu tiên các tài liệu ngắn với tên tệp rõ ràng.
- Liên kết các artifact liên quan với nhau.
- Lưu trữ các quy tắc lâu bền, không phải bản ghi cuộc họp.
- Cập nhật repo trong cùng phiên mà quyết định được đưa ra.

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

- Một agent mới có thể khám phá quy tắc liên quan mà không cần hỏi con người.
- Cùng một sự thật không bị phân tán qua nhiều tệp mâu thuẫn.
- Artifact mới nằm gần mã hoặc workflow mà nó điều chỉnh.

layered-domain-architecture.md

# SOP: Kiến trúc Domain Phân lớp

Sử dụng SOP này khi agent tiếp tục vi phạm ranh giới, sao chép logic qua các lớp, hoặc tạo ra mã khó review sau một vài phiên.

## Mục tiêu

Làm cho ranh giới domain đủ rõ ràng để agent có thể di chuyển nhanh mà không âm thầm làm xuống cấp cấu trúc.

## Mô hình Mục tiêu

Trong một domain kinh doanh, ưu tiên luồng định hướng này:

`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 provider hoặc adapter rõ ràng. Các utils dùng chung nằm bên ngoài domain và không nên tích lũy logic domain.

## Danh sách Kiểm tra Thiết lập

- Định nghĩa các domain hiện tại trong `ARCHITECTURE.md`.
- Viết các hướng phụ thuộc được phép trong `ARCHITECTURE.md`.
- Ghi lại các giao diện xuyên suốt như auth, telemetry và external API.
- Thêm một ghi chú ngắn cho vi phạm ranh giới khó nhất hiện tại.
- Quyết định những gì nên được thực thi cơ học bởi lint, test hoặc script.

## SOP Thực thi

1. Ánh xạ codebase thành các domain trước khi chạm vào phong cách triển khai.
2. Cho mỗi domain, xác định chuỗi lớp được phép.
3. Xác định tất cả các mối quan tâm xuyên suốt và định tuyến chúng qua các provider hoặc adapter.
4. Di chuyển logic dùng chung mơ hồ sang domain sở hữu hoặc sang utils thực sự chung chung.
5. Ghi lại các quy tắc trong `ARCHITECTURE.md`.
6. Thêm một guardrail có thể thực thi cho vi phạm có chi phí cao nhất.
7. Cập nhật điểm chất lượng sau khi thay đổi.

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

- Một agent mới có thể biết lớp nào sở hữu một thay đổi.
- Mã UI không còn tiếp cận vào repo hoặc side effect bên ngoài trực tiếp.
- Các mối quan tâm xuyên suốt có các điểm đầu vào được đặt tên.
- Ít nhất một ranh giới quan trọng được thực thi cơ học.

## Artifact Repo Cần Cập nhật

- `ARCHITECTURE.md`
- `docs/QUALITY_SCORE.md`
- `docs/design-docs/` khi lý luận thay đổi
- `docs/PLANS.md` hoặc kế hoạch thực thi active

observability-feedback-loop.md

# SOP: Vòng lặp Phản hồi Observability

Sử dụng SOP này khi debug chậm, agent tiếp tục tuyên bố thành công mà không có bằng chứng, hoặc hành vi runtime khó kiểm tra hơn bản thân mã.

## Mục tiêu

Cung cấp cho agent một vòng lặp phản hồi cục bộ qua log, metrics, trace và workload có thể chạy để nó có thể lý luận từ thực thi, không chỉ từ kiểm tra mã.

## Stack Tối thiểu

- ứng dụng phát ra các log có cấu trúc
- ứng dụng phát ra metrics và trace khi khả thi
- lớp fan-out hoặc thu thập cục bộ
- giao diện truy vấn cho log, metrics và trace
- workload hoặc user journey có thể lặp lại để chạy lại sau mỗi thay đổi

## SOP Thực thi

1. Định nghĩa các journey runtime vàng quan trọng nhất.
2. Thêm các log có cấu trúc vào khởi động và đường dẫn quan trọng.
3. Thêm metrics cho độ trễ, số lần thất bại hoặc độ sâu hàng đợi khi hữu ích.
4. Thêm trace hoặc marker timing cho các luồng chậm hoặc nhiều bước.
5. Làm cho các tín hiệu có thể truy vấn từ môi trường dev cục bộ.
6. Cung cấp cho agent một workload hoặc kịch bản có thể lặp lại để chạy lại.
7. Yêu cầu vòng lặp: truy vấn -> tương quan -> lý luận -> triển khai -> khởi động lại -> chạy lại -> xác minh.

## Danh sách Kiểm tra Phiên Debug

- Điều gì đã thất bại?
- Tín hiệu nào chứng minh sự thất bại?
- Lớp nào sở hữu sự thất bại?
- Điều gì thay đổi sau khi sửa?
- Ứng dụng có khởi động lại sạch sẽ không?
- Cùng workload có vượt qua sau khi chạy lại không?

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

- Agent có thể giải thích một chế độ thất bại từ bằng chứng runtime.
- Cùng workload có thể được chạy lại sau mỗi thay đổi.
- Khởi động lại và chạy lại là một phần của vòng lặp tác vụ bình thường.
- Các tín hiệu độ tin cậy được ghi lại trong `docs/RELIABILITY.md`.