Cách Viết Bài Cho Agent

Mọi page trong handbook đều có nút Copy cho Agent — paste vào Claude Code, ChatGPT, hoặc agent khác để chỉ đường. Để output đó effective, page phải có cấu trúc dễ parse.

Đây là template chuẩn của team. Áp dụng cho mọi page mới và mọi rewrite.

Ý tưởng lõi: Page là input cho agent, không chỉ cho người. Cấu trúc rõ → agent đọc đúng → kết quả đúng.

Cấu trúc chuẩn

Mọi page nên theo skeleton này. Tối thiểu cần Intro + 1 section nội dung — các section khác là tuỳ chọn theo doc type.

[Intro 1-2 câu — page này là gì, khi nào cần đọc]

> Ý tưởng lõi: [1 câu]

## Khi nào dùng / Khi nào áp dụng     (tuỳ chọn)
## Nguyên tắc / Quy tắc                (nếu có rule cứng)
## Quy trình / Workflow / Cách làm     (nếu là procedural)
## Tham khảo / Ví dụ                   (cụ thể, link, code)
## Tránh / Fail mode                   (nếu có anti-pattern)
## Liên quan                           (links tới page khác)

Chọn template theo doc type

Loại doc	Section bắt buộc	Ví dụ
Workflow / SOP	Nguyên tắc + Quy trình + Tránh	Quy Trình Phát Triển Sản Phẩm
Pattern / Recipe	Cách làm + Ví dụ	Cách Tích Hợp DataForSEO
Reference	Khái niệm + Tham khảo	Các Khái Niệm Chính
Tutorial / How-to	Quy trình + Ví dụ	Cách Sử Dụng Git
Case study	Bối cảnh + Cách làm + Kết quả	Cách Phát Triển Image Agent

Format conventions

Heading levels

• # không dùng trong body. Title đã có ở field title của page (handbook tự render thành h1).
• ## — major section.
• ### — sub-section / bước con trong section.

Core idea blockquote

Mỗi page có một blockquote "Ý tưởng lõi" near top, ngay sau intro. Agent đọc đây trước để hiểu intent.

> **Ý tưởng lõi**: Câu chốt nhất của page.

Rules / Principles

Numbered list trong section "Nguyên tắc". Mỗi rule mở đầu bằng bold để agent scan ra.

1. **Rule one.** Giải thích ngắn 1 câu.
2. **Rule two.** ...

Workflow steps

Dùng ### Bước N. {Tên} hoặc ### Step N. Agent recognize "Bước N" / "Step N" → treat as sequential workflow.

### Bước 1. {Tên}

Mô tả + chi tiết.

### Bước 2. {Tên}

...

Anti-patterns / Fail modes

Blockquote với prefix Fail mode: hoặc Tránh:. Agent recognize → treat as hard avoidance.

> **Fail mode:** Mô tả lỗi + hậu quả. Đã có incident → kiểm tra mỗi PR.

Code blocks

Fenced với language identifier (bash, typescript, sql, json...). Agent dùng language hint để parse đúng cú pháp.

```bash
railway run --service Postgres bun run dev
```

Inline code dùng backticks: npm run dev, lib/db.ts.

Khi nào "Copy cho Agent" có ích

• Trước khi thực thi quy trình: copy SOP → paste vào Claude Code với prompt "thực thi theo quy trình này".
• Trước khi xây tính năng tương tự: copy pattern → "đọc nội dung này để hiểu cách team làm".
• Khi debug: copy reference page → "lookup khái niệm này".
• Khi onboard người mới: copy nhiều page liên quan → "tóm tắt cho người mới vào team".

Tránh

Fail mode: Viết page dạng "stream of consciousness" — không section, không bullet. Agent paste vào nhận khối text dày → trả về output mơ hồ.

Fail mode: Bullet không bold lead. - Không cài bằng tay, không hardcode credential, ... Mỗi gạch đầu dòng là 1 rule khác nhau → agent khó tách. Đổi thành numbered list với bold lead.

Fail mode: Anti-pattern viết inline thành câu trần thuật — "Đừng push thẳng main." Agent đọc qua loa. Wrap thành blockquote Fail mode: để được highlight là hard rule.

Fail mode: Code block không có language tag. Agent đoán cú pháp → có khi format lại sai. Luôn ghi ```bash, ```ts, ...

Liên quan

• Cách Mình Viết Documentation — viết doc cho người, README, CHANGELOG.
• Quy Trình Phát Triển Sản Phẩm — ví dụ page áp dụng đúng format này.