Capture as intent.md (Stage 1: Plan)

1. Những thay đổi: Capture intent.md

File intent.md khởi động quy trình phát triển phần mềm, có thể đi vào qua nhiều luồng khác nhau: một người có ý tưởng, một ticket được ghi nhận, hoặc một sự cố phát sinh qua cảnh báo (xem Stage 6: Maintain).

Khi một người có ý tưởng, họ trao đổi (brainstorm) với Claude và tạo ra một bản proto-spec định dạng Markdown. Trong quy trình SDLC truyền thống, cùng người đó phải thuyết phục một thành viên của đội sản phẩm (product team) cùng viết hoặc viết thay cho họ.

Bản proto-spec do Claude tạo ra con người đọc hiểu được, được quản lý phiên bản (version controlled), và có thể sử dụng ngay cho giai đoạn tiếp theo. Bản proto-spec này được lưu thành intent.md.

Dù intent bắt nguồn từ sự kiện kích hoạt (event trigger) hay từ một người, các bước áp dụng đều như nhau: Product Owner xem xét và hiệu chỉnh bản intent.md do agent soạn thảo trước khi được commit.

2. Sơ đồ Ingestion & Approval Gate

intent.md đi vào chu trình phát triển qua 3 kênh thu nhận:

• Ý tưởng từ con người (A person has an idea): Trao đổi (brainstorm) với Claude để tạo proto-spec bằng ngôn ngữ tự nhiên.
• Ticket được ghi nhận (A ticket is filed): Yêu cầu hoặc lỗi được ghi nhận trên hệ thống theo dõi.
• Sự cố phát sinh qua cảnh báo (An incident is surfaced via an alert): Cảnh báo sự cố từ hệ thống vận hành (xem Stage 6: Maintain).

Dù intent bắt nguồn từ sự kiện kích hoạt hay từ một người, cùng một quy trình được áp dụng: Product Owner xem xét và hiệu chỉnh intent.md do agent soạn thảo trước khi được commit.

3. Bắt đầu: Hạ tầng & Git Connector

• Điều kiện tiên quyết (Prerequisites): Không có (None).
• Hạ tầng (Infrastructure): Quyền truy cập Claude cho người không phải kỹ sư (claude.ai hoặc Cowork); một template intent.md đã thống nhất; một nơi lưu trữ chung được quản lý phiên bản (shared, version-controlled home) mà Product Owner theo dõi.

Đối với một sản phẩm đơn lẻ, nơi lưu trữ đơn giản nhất là thư mục intent/ ngay trong repository của sản phẩm. Cách bố trí này giữ chuỗi artifact nằm liền kề mã nguồn sinh ra từ nó. Một intent repository riêng chỉ đáng với chi phí quản lý khi intent trải dài qua nhiều repository; còn trong monorepo, nó là một thư mục. Mục Legacy systems trong Stage 3: Build sẽ đề cập đến mối liên hệ giữa nơi lưu trữ này với Jira hoặc công cụ quản lý yêu cầu đang nắm giữ bản ghi.

Việc thiết lập này là nhiệm vụ một lần của đội ngũ platform hoặc kỹ thuật. Một thành viên kỹ thuật cần khởi tạo intent home và quyết định ai có quyền ghi vào đó, vì nhiều người đóng góp sẽ đến từ nhiều bộ phận khác nhau trong toàn tổ chức.

Sau khi repository đã tồn tại, những người đóng góp không có kinh nghiệm về Git không cần phải sử dụng Git trực tiếp. Thay vào đó, một trình kết nối tới hệ thống quản lý phiên bản (như GitHub) cho phép Claude thay mặt họ commit các file Markdown trực tiếp từ claude.ai hoặc Cowork (self-service pattern).

4. Các bước thực thi

Quá trình chuyển hóa ý tưởng thành intent.md diễn ra qua 5 bước:

5. Cấu trúc mẫu chuẩn của intent.md

Hình thái cụ thể của intent.md theo mẫu self-service pattern từ nguyên tác:

# Intent: claims status self-service
Author: J. Ortiz (claims operations). Status: draft.

## Problem
Customers phone the contact center to ask where their claim is.
Handlers spend roughly a third of call time on status-only queries.

## Proposed outcome
Customers see claim status, next step and expected date in the portal.

## Affected users and systems
Claims handlers, portal team, claims-core API.

## Constraints
No new PII in the portal session. Existing authentication only.

## Open questions
Do third-party loss adjusters need access too?

Cấu trúc chuẩn gồm 5 phần chính:

• Problem (Bài toán): Khách hàng gọi điện đến trung tâm liên lạc hỏi tình trạng hồ sơ bồi thường; nhân viên xử lý mất khoảng một phần ba thời gian cuộc gọi cho các câu hỏi chỉ để hỏi trạng thái.
• Proposed outcome (Kết quả đề xuất): Khách hàng nhìn thấy trạng thái hồ sơ bồi thường, bước tiếp theo và ngày dự kiến ngay trên portal.
• Affected users and systems (Người dùng & hệ thống bị ảnh hưởng): Nhân viên xử lý bồi thường (claims handlers), đội ngũ portal, API lõi bồi thường (claims-core API).
• Constraints (Ràng buộc): Không đưa thêm PII (thông tin định danh cá nhân) mới vào phiên làm việc portal; chỉ sử dụng cơ chế xác thực hiện có.
• Open questions (Câu hỏi mở): Các giám định viên tổn thất bên thứ ba (third-party loss adjusters) có cần quyền truy cập không?

6. Kiểm soát & Đo lường hiệu quả

Cân nhắc quản trị (Governance considerations): Bằng chứng là file intent.md đã được commit, ghi nhận tác giả (author), mốc thời gian (timestamp) và toàn bộ lịch sử chỉnh sửa (revision history). Dữ liệu này được ghi nhận trong Git history của intent home. Product Owner phê duyệt, và quyết định chấp thuận (accept) hoặc từ chối (reject) để đưa intent vào Stage 2: Design được ghi nhận dưới dạng merge commit hoặc closing review.