Ở các bài trước, bạn đã học cách kết nối Notion MCP với từng công cụ riêng lẻ (Claude Code, OpenCode, Gemini CLI, Cursor). Bài này ghép mọi thứ lại thành một workflow hoàn chỉnh, dùng thật trong dự án: lấy Notion làm nguồn requirement duy nhất (source of truth), để AI agent đọc spec, sinh implementation plan (kế hoạch triển khai), cập nhật trạng thái công việc theo thời gian thực, và tự publish release note ngược lại Notion khi hoàn tất. Đây là mô hình spec-driven development (phát triển hướng theo spec) được hỗ trợ bởi AI agent — không phải lý thuyết, mà là quy trình có thể áp dụng ngay từ ngày mai cho team bạn.
Tổng Quan Workflow: Spec-Driven Development Với Notion Là Source Of Truth
Trước khi vào chi tiết từng bước, cần thống nhất nguyên tắc nền tảng: Notion là nơi duy nhất chứa "sự thật" về requirement, code và mọi tài liệu khác chỉ là hệ quả được sinh ra từ đó. Điều này nghe hiển nhiên nhưng thực tế rất nhiều team để requirement "rò" ra nhiều nơi — Slack, email, comment trong PR — dẫn đến không ai biết bản nào là bản đúng nhất khi có tranh cãi.
Workflow tổng thể gồm 4 giai đoạn, lặp lại theo từng feature/sprint:
- Spec được viết/duyệt trên Notion (page trong database "Requirements", có property Status, Priority, Owner).
- AI agent đọc spec, sinh implementation plan — một page con hoặc block con liệt kê các bước kỹ thuật cụ thể, review bởi engineer trước khi bắt tay code.
- Trong quá trình code, agent cập nhật property Status và acceptance criteria (tiêu chí chấp nhận) ngay khi từng phần hoàn tất — không đợi tới cuối sprint.
- Khi merge/release, agent tự publish release note về lại Notion, đóng vòng lặp — biến Notion thành nơi bất kỳ ai (kể cả non-engineer) đều tra được trạng thái thật của feature.
Sơ đồ luồng dữ liệu (mô tả bằng text):
[Notion: Spec] --(agent đọc)--> [Implementation Plan] --(engineer review)--> [Code]
^ |
|------------------ (agent cập nhật Status/Release Notes) <---------------|
Điểm khác biệt so với quy trình "viết tài liệu sau khi xong việc" truyền thống: ở đây, việc đồng bộ Notion là một phần của quy trình code, không phải công việc phụ làm sau — vì chi phí để agent làm việc này gần như bằng không so với việc engineer tự làm tay.
Mẹo: Thiết lập một database "Requirements" với schema chuẩn hoá (Status, Priority, Owner, Implementation Status, Linked PR) ngay từ đầu, trước khi áp dụng AI agent vào workflow. Agent làm việc tốt nhất khi schema database nhất quán — schema lộn xộn sẽ khiến agent cập nhật sai field hoặc tạo property trùng lặp.
Bước 1: Đọc Spec Notion Và Sinh Implementation Plan
Khi bắt đầu một feature mới, bước đầu tiên là để agent đọc spec và sinh ra một implementation plan chi tiết — không phải để agent tự code ngay, mà để bạn (engineer) review kế hoạch trước khi bắt tay vào việc, giống hệt nguyên tắc "plan trước khi code" trong agentic engineering nói chung.
Ví dụ prompt (dùng được với Claude Code hoặc Cursor Agent Mode, đã kết nối Notion MCP):
Đọc page Notion "Feature Spec: Subscription Auto-Renewal" trong database "Requirements".
Sinh một implementation plan gồm:
1. Danh sách các thay đổi cần làm trên code (module, file dự kiến ảnh hưởng)
2. Các case cần test (bao gồm edge case: thẻ hết hạn, retry payment thất bại)
3. Thứ tự thực hiện đề xuất, đánh dấu phần nào có thể làm song song
4. Câu hỏi cần xác nhận với PM trước khi bắt đầu (nếu spec có phần mơ hồ)
Không code ngay, chỉ ra plan để tôi review.
Sau khi tôi duyệt, tạo một page con "Implementation Plan" dưới page spec này trong Notion.
Phần "câu hỏi cần xác nhận với PM" ở bước 4 rất quan trọng và hay bị bỏ qua — một agent tốt phải chủ động chỉ ra phần spec mơ hồ hoặc thiếu thông tin, thay vì tự đưa ra giả định rồi im lặng code theo giả định đó. Đây chính là kinh nghiệm thực chiến: phần lớn bug "đúng theo AI hiểu nhưng sai theo ý PM" xuất phát từ việc agent tự lấp khoảng trống thay vì hỏi lại.
Sau khi bạn duyệt plan (có thể sửa trực tiếp trong chat trước khi cho ghi vào Notion), page con "Implementation Plan" được tạo dưới spec gốc — giữ được liên kết ngữ cảnh (spec nào sinh ra plan nào), dễ tra cứu về sau.
Mẹo: Luôn yêu cầu agent liệt kê câu hỏi mơ hồ TRƯỚC khi sinh plan chi tiết, không phải sau. Nếu để agent sinh plan đầy đủ rồi mới hỏi, bạn dễ bị cuốn theo chi tiết plan mà bỏ sót việc câu hỏi nền tảng chưa được trả lời.
Bước 2: Cập Nhật Status Và Acceptance Criteria Trong Lúc Code
Đây là phần biến workflow từ "làm được một lần cho vui" thành "áp dụng được lâu dài trong team" — vì nó loại bỏ gần hết công việc thủ công cập nhật tracker mà kỹ sư thường trì hoãn hoặc quên.
Thiết lập quy ước: mỗi khi hoàn thành một mục trong implementation plan hoặc một acceptance criteria (tiêu chí chấp nhận, thường là các dòng checklist trong spec dạng "Given/When/Then" hoặc bullet điều kiện hoàn thành), bạn báo ngắn cho agent, agent tự cập nhật Notion:
Tôi vừa hoàn thành phần "Retry payment logic với exponential backoff"
trong implementation plan của feature Subscription Auto-Renewal.
Đánh dấu mục này là hoàn thành (check to_do block) trong page Implementation Plan,
và trong page spec gốc, cập nhật acceptance criteria "Hệ thống retry tối đa 3 lần
trước khi đánh dấu payment failed" thành đã pass (thêm ✅ hoặc đổi property tương ứng).
Với việc cập nhật property Status tổng thể của feature (ví dụ "To Do" → "In Progress" → "In Review" → "Done"), nên gắn vào các cột mốc rõ ràng trong quy trình team (mở PR, PR approved, deploy production) thay vì để agent tự đoán khi nào nên đổi:
PR #915 cho feature Subscription Auto-Renewal đã được approve và merge vào main.
Cập nhật Status trong database "Requirements" thành "In Review" (chờ QA),
và thêm comment vào page spec: "Code merged via PR #915, chờ QA verify trên staging."
Việc gắn cập nhật Notion vào đúng các mốc quy trình (không phải tuỳ hứng) giúp Status trên Notion phản ánh đúng ý nghĩa nhất quán cho toàn team, tránh tình trạng "In Progress" bị hiểu khác nhau giữa các feature.
Mẹo: Định nghĩa rõ ràng ý nghĩa từng giá trị Status (ví dụ "In Review" luôn có nghĩa là code đã merge, đang chờ QA — không phải "đang review code") và ghi vào chính page hướng dẫn sử dụng database. Agent sẽ áp dụng đúng quy ước này nếu bạn cho nó đọc page hướng dẫn đó trước khi cập nhật lần đầu trong phiên làm việc.
Bước 3: Tự Động Publish Release Notes Và Tài Liệu Về Lại Notion
Giai đoạn cuối, khép vòng lặp: khi feature đã deploy, thay vì để việc viết release note (ghi chú phát hành) "rơi" xuống cuối danh sách ưu tiên rồi thường bị bỏ qua, giao thẳng cho agent — vì nó có sẵn toàn bộ ngữ cảnh từ code, PR, và spec gốc để viết chính xác hơn cả một người phải nhớ lại sau nhiều ngày.
Feature Subscription Auto-Renewal đã deploy lên production thành công
(deploy log đính kèm, PR #915, #920, #924 liên quan).
Viết một entry release note, thêm vào page "Release Notes" trong Notion
(entry mới nhất ở đầu page), theo format:
## [Ngày hôm nay] Subscription Auto-Renewal
- Mô tả ngắn tính năng dành cho người dùng cuối (không dùng thuật ngữ kỹ thuật)
- Ghi chú kỹ thuật cho engineer (retry logic, các flag cấu hình nếu có)
- Link tới page spec gốc và các PR liên quan
Đồng thời, cập nhật Status trong database Requirements thành "Done".
Yêu cầu tách riêng "mô tả cho người dùng cuối" và "ghi chú kỹ thuật cho engineer" trong cùng entry là một pattern rất hữu ích — vì release note trên Notion thường được đọc bởi cả hai nhóm đối tượng khác nhau (support/sale cần bản dễ hiểu, engineer khác cần chi tiết kỹ thuật để debug sau này).
Với các dự án có compliance/audit requirement, bạn có thể mở rộng thêm bước: yêu cầu agent tạo một page riêng "Change Log - Audit Trail" ghi timestamp chính xác, người thực hiện, và toàn bộ danh sách PR — phục vụ việc tra soát sau này mà không cần lục lại Slack hay git log thủ công.
Mẹo: Luôn để agent trích dẫn số PR cụ thể (không chỉ nói "đã fix một số bug") trong release note. Khi có sự cố production cần rollback hoặc điều tra nguyên nhân, số PR cụ thể giúp truy vết ngay lập tức, tiết kiệm hàng giờ so với việc phải đoán PR nào liên quan.
Mẹo Tổng Hợp Để Duy Trì Workflow Này Bền Vững Trong Team
Một workflow chỉ có giá trị nếu team duy trì được nó lâu dài, không chỉ chạy tốt trong buổi demo. Vài kinh nghiệm thực chiến để workflow này không "chết" sau vài tuần:
- Chuẩn hoá schema Notion trước, mở rộng AI sau — đừng cố gắn AI vào một hệ thống Notion đang lộn xộn, sửa schema (tên property, option chuẩn) trước.
- Luôn có bước review của người trước khi ghi dữ liệu quan trọng — implementation plan, release note đều nên qua review nhanh, không tự động publish 100% không giám sát.
- Theo dõi rate limit và giới hạn block khi mở rộng ra nhiều team — nếu nhiều người cùng dùng chung một integration token, bạn có thể chạm rate limit của Notion API nhanh hơn dự kiến; cân nhắc tách integration theo team hoặc theo mục đích sử dụng.
- Định kỳ audit lại các page do AI tạo/sửa (hàng tháng là hợp lý) để phát hiện sớm các pattern lỗi lặp lại (format sai, property bị đặt nhầm) và điều chỉnh prompt chuẩn cho cả team dùng chung.
Mẹo: Lưu toàn bộ prompt mẫu đã dùng trong 3 bước của workflow này (đọc spec → sinh plan, cập nhật status, publish release note) thành một page "AI Workflow Playbook" ngay trong chính Notion của team. Đây vừa là tài liệu hướng dẫn, vừa là minh chứng sống cho việc AI agent có thể duy trì tài liệu về chính quy trình sử dụng AI — một vòng lặp khép kín rất phù hợp với tinh thần dogfooding trong agentic engineering.