Context Hub: Khi Agent Cần Biết Stripe Vừa Đổi API

TL;DR

Agent code API theo training data cũ, runtime mới biết sai, không phải compile time.
chub get stripe/api --lang py lấy docs hiện tại trong vài giây, agent đọc trước khi code.
Dành cho dev dùng Claude Code, Cursor, Copilot gọi third-party API hay thay đổi.
chub annotate ghi gotcha cục bộ, lần sau agent tự đọc, không cần nhắc lại.
12.8k stars trong 6 tháng, Andrew Ng ký tên, cùi bắp nhưng vá đúng chỗ rách.

Lần Đầu Tôi Thấy Agent Tự Tin Sai

Claude Code viết xong Stripe integration. Code đẹp, có retry logic, có idempotency key. Tôi chạy test.

Lỗi đầu tiên: tham số card trong stripe.customers.create() đã deprecated từ Q1 2024, phải đổi sang payment_method. Sửa xong.

Lỗi thứ hai: webhook verification thất bại vì tôi đã parse JSON trước khi verify. Stripe cần raw body. Đúng là ghi trong docs, chỉ là docs của năm ngoái.

Hai lỗi. Một session. Agent không sai kỹ thuật, nó chỉ đang sống trong năm 2023. Phần đáng lo là nó không biết mình không biết điều đó.

Như bác sĩ nhớ phác đồ điều trị từ hồi học y khoa, cứ thế kê thuốc, dù guideline đã cập nhật ba lần từ đó đến nay. Bệnh nhân mới phát hiện khi uống thuốc không bớt.

Repo Này Làm Gì

Context Hub là một CLI nhỏ gọn và một kho docs curated có version. Agent chạy chub get <id> trước khi code và nhận docs mới nhất, không phải training data cũ. Repo này là cầu nối giữa knowledge cutoff của model và API docs đang chạy trên production hôm nay.

Nội dung trong kho chia làm hai loại, và phân biệt này quan trọng hơn tên repo:

	Docs	Skills
Là gì	”Cần biết gì” — API reference, spec	”Làm thế nào” — workflow, patterns
Ví dụ	OpenAI Chat API, Stripe payments	Playwright login flow, test automation
Kích thước	10K đến 50K token	Dưới 500 dòng
Cài vào đâu	`.context/` hoặc file tạm	`.claude/skills/`, `.cursor/rules/`
Có version?	Có (Python vs JS, v1 vs v2)	Không — language-agnostic

CLI tự nhận biết loại. Chỉ một lệnh chub get <id> cho cả hai, không cần phân biệt.

Nhưng có một thứ tôi chỉ dùng từ tuần thứ hai, và đó lại là thứ tôi dùng nhiều nhất bây giờ.

Bốn Tình Huống Thực Chiến

OpenAI Chat API format mới: Chạy chub get openai/chat-api --lang py. Agent nhận spec messages format hiện tại thay vì format cũ từ 2023. Code ra chạy ngay lần đầu, không cần lục changelog.
Stripe webhook gotcha: Chạy chub get stripe/api --full. Flag --full kéo cả entry point lẫn reference files. Trong đó có note về raw body required cho webhook verification. Agent đọc, viết đúng ngay lần đầu.
Playwright login flow: chub get pw-community/login-flows trả về skills, không phải docs. Agent cài vào .claude/skills/ và tự biết dùng khi gặp auth flow. Không cần nhắc mỗi session.
chub annotate — cái tôi nhắc từ đầu: Session trước phát hiện gotcha. Session kết thúc. Session mới, agent không nhớ gì. chub annotate stripe/api "raw body gotcha" là tờ post-it dán lên bìa sách: lần sau mở ra là thấy ngay, không cần tra lại từ đầu.

Bốn tình huống này đều chạy ngon trên máy bạn. Còn agent đang chạy trong CI container không có ~/.chub của bạn — câu chuyện đó ở phần sau.

Dùng Thế Nào

Cài:

npm install -g @aisuite/chub

Tìm docs có sẵn:

chub search stripe
# stripe/api          Stripe API Reference (v2024-11-20)    js, py
# stripe/payments     Stripe Payments quick start           js, py
# stripe/webhooks     Stripe Webhook best practices         --

Lấy docs và lưu vào workspace:

chub get stripe/api --lang py -o .context/stripe.md

Ghi chú phát hiện vừa xảy ra:

chub annotate stripe/api "Webhook cần raw body -- KHÔNG parse JSON trước khi verify signature"

Lần sau chạy chub get stripe/api, annotation tự xuất hiện ở cuối output:

---
[Agent note  -  2026-03-08T17:42:00Z]
Webhook cần raw body -- KHÔNG parse JSON trước khi verify signature

Agent đọc, biết trước. Không cần nhắc thêm gì.

Khi docs có nhiều phần, output cuối thêm vào:

---
Additional files available (use --file to fetch):
  references/webhooks.md
  references/errors.md
Example: chub get stripe/api --file references/webhooks.md

Agent đọc overview trước, quyết định fetch thêm phần nào. Tiết kiệm token thay vì kéo cả bộ 50K vào mỗi session.

💡 Tip: Dùng chub get <id> --json nếu bạn muốn pipe output vào script hoặc agent framework tự xử lý metadata: version, ngôn ngữ, danh sách reference files có sẵn.

Markdy animation

Tool mới, kịch bản mới, phải giải thích lại từ đầu mỗi session. Trừ khi bạn bỏ hướng dẫn đó vào bộ nhớ dài hạn của agent.

Cài Skill Một Lần, Không Cần Nhắc Mỗi Session

Docs thì mỗi task phải fetch lại vì API thay đổi. Skills thì cài một lần, agent tự biết dùng khi cần.

mkdir -p ~/.claude/skills
cp $(npm root -g)/@aisuite/chub/skills/get-api-docs/SKILL.md ~/.claude/skills/get-api-docs.md

Sau bước này Claude Code tự chạy chub get mỗi khi xác định cần API docs. Cursor, Aider hay bất kỳ agent nào đọc custom instructions cũng dùng được — copy SKILL.md vào thư mục rules tương ứng.

Cài xong skills rồi, câu hỏi còn lại là: ai thật sự cần cái này, ai không cần.

Dành Cho Ai

Ngắn gọn nhất: ai hay để agent viết code gọi third-party API có breaking changes thường xuyên.

Claude Code, Cursor, Copilot, Aider, bất kỳ coding agent nào hỗ trợ shell access hoặc MCP
GitHub Actions pipeline chạy agent trước khi deploy
Team chia sẻ annotations cho gotcha đã biết qua git (commit thủ công ~/.chub/annotations/)

Node.js >= 18. Không cần setup server. Không cần API key.

Context Hub không thay thế RAG pipeline cho private docs. Nó vá knowledge cutoff theo kiểu on-demand fetch, không xây knowledge base từ codebase riêng của bạn. Có vài chỗ cần biết trước khi cài vào CI.

Anh Em Cẩn Thận Mấy Chỗ Này

⚠️ Warning: Annotations lưu tại ~/.chub/annotations/ trên máy cục bộ. Không sync tự động. Nếu bạn chạy agent trong CI container, annotations trên máy dev sẽ không có ở đó. Phải commit file thủ công hoặc bake vào container image.

Vài thứ nên biết trước:

Nội dung không đầy đủ: Context Hub là community-driven. API bạn cần có thể chưa có hoặc đã stale. Chạy chub search <tên> để kiểm tra trước.
Incremental fetch: Docs lớn chia thành entry point và reference files. Dùng --full để kéo hết, hoặc --file references/webhooks.md để kéo từng phần khi cần.
Trust boundary: Khi chub get, request đi ra server của AI Suite. Với codebase nhạy cảm, xem xét dùng --json output và xử lý offline, hoặc cài BYOD local registry.
Feedback là opt-in: chub feedback stripe/api up gửi vote về cộng đồng. Chỉ chạy khi bạn chủ động muốn đóng góp.

Agent Không Sai, Nó Chỉ Không Biết Cái Nó Không Biết

Tôi quay lại project Stripe sau khi cài context-hub. Lần này agent chạy chub get stripe/api ngay đầu task, đọc annotation về raw body tôi đã để lại từ session trước, và viết webhook handler đúng từ lần đầu.

Không phải vì model giỏi hơn. Mà vì lần này nó biết cái nó không biết.

12.824 stars trong 6 tháng, tính từ ngày Andrew Ng push commit đầu tiên. Ông không hay ký tên vào thứ không đáng tin. Phần còn lại agent của bạn tự quyết định.

andrewyng/context-hub · MIT · 12.8k stars