Build Claude Code Agent đầu tiên của bạn
Build Claude Code Agent đầu tiên của bạn: Một hệ thống quản lý dự án đơn giản giúp tiết kiệm hàng giờ
Cách một skill chỉ gồm 300 dòng lại trở thành công cụ cho hiệu suất cao trong quá trình phát triển phần mềm có sự hỗ trợ của AI.
Hãy thử tưởng tượng: Vào một buổi đêm và bạn đang nhìn chằm chằm vào một thông báo lỗi quen thuộc đến ám ảnh. “Kết nối bị từ chối trên cổng 5432”. Bạn đã từng thấy điều này trước đây. Bạn biết mình đã từng giải quyết nó rồi. Nhưng ở đâu? Khi nào? Thông báo lỗi chỉ ghi “đã sửa kết nối cơ sở dữ liệu”. Stack Overflow đưa ra cho bạn mười hai câu trả lời khác nhau. Trợ lý AI của bạn vui vẻ đề xuất các giải pháp mà bạn đã thử rồi.
Đây chính là chứng “mất trí nhớ” của AI, và nó khiến bạn phải trả giá đắt hơn bạn tưởng.
Mọi trợ lý lập trình AI đều có cùng một hạn chế gây khó chịu: chúng quên mọi thứ giữa các phiên làm việc. Bắt đầu một cuộc trò chuyện mới, và Claude không biết rằng hôm qua bạn đã dành 45 phút để tìm ra môi trường thử nghiệm của mình sử dụng cổng 5433, chứ không phải 5432. Nó không nhớ rằng bạn đã chọn PostgreSQL thay vì MongoDB vì chuyên môn hiện có của nhóm bạn. Nó không thể nhớ rằng lỗi “kết nối bị từ chối” luôn có nghĩa là VPN đã bị ngắt kết nối. Hoặc nó bắt đầu sử dụng một thư viện xử lý ngôn ngữ tự nhiên (NLP) hoặc thư viện biểu đồ mới trong khi toàn bộ dự án đang sử dụng một thứ khác và bạn đã quyết định cái nào mình muốn dùng. Rồi bạn lại phải giải thích lại. Và lại giải thích nữa.
Tất cả kiến thức khó nhọc tích lũy được đều biến mất...
Có một phương pháp đã được thử nghiệm là liên kết các tệp markdown nhỏ từ tệp CLAUDE.md để theo dõi các quyết định, lỗi và các thông tin quan trọng. Một ý tưởng được phát triển từ đó: Điều gì sẽ xảy ra nếu ta có thể tạo ra một kỹ năng quản lý việc này một cách tự động?
Ý tưởng đó đã trở thành project-memory để thử nghiệm. Mặc dù cực kỳ đơn giản (dưới 300 dòng), nó thực sự đã giúp tôi tiết kiệm hàng giờ làm việc. Hướng dẫn này sẽ chỉ cho bạn cách xây dựng kỹ năng quản lý bộ nhớ dự án của riêng mình và quan trọng hơn, cách suy nghĩ về việc tạo ra các kỹ năng giải quyết các vấn đề thực tế.
Claude Code không còn là người chơi duy nhất nữa. Codex, GitHub Copilot và OpenCode đều đã tuyên bố hỗ trợ cho các Agentic Skills. Thậm chí còn có một chợ ứng dụng dành cho các kỹ năng lập trình tự động hỗ trợ Gemini, Aidr, Qwen Code, Kimi K2 Code, Cursor, và nhiều hơn nữa; hơn 14 nền tảng và con số này vẫn đang tăng lên với trình cài đặt kỹ năng lập trình tự động phổ quát (skilz). Trong suốt hướng dẫn này, tôi sẽ sử dụng "Claude" và "lập trình tự động" thay thế cho nhau, giống như nói "Xerox tờ giấy này" thay vì "copy tờ giấy này". (Bạn cũng có thể sử dụng Claude Code, OpenCode và Gemini CLI hơn trong quy trình làm việc của mình.)
Cái giá thực sự của chứng mất trí nhớ do AI gây ra
Một kịch bản quen thuộc xảy ra như sau:
Tháng 1: Khám phá
Error: CORS policy blocked request from localhost:3000
[2 hours of debugging, trying proxy configs, header changes, nginx rewrites]
Solution: Add proxy configuration to package.json
Tháng 6: Phát hiện lỗi
Error: CORS policy blocked request from localhost:3000
Developer: "This looks familiar... how did we fix this?"
[Searches old commits, checks Stack Overflow again, asks Claude who has no memory]
[1 hour to re-discover the exact same proxy config solution]
Nghe quen phỉa không? Đây là sự thật khó chịu: Trợ lý lập trình AI thực sự làm cho vấn đề trở nên tồi tệ hơn chứ không tốt hơn. Không có bộ nhớ:
Mỗi phiên trò chuyện mới bắt đầu từ con số không
Mỗi lỗi đều có cảm giác như bạn đang giải quyết nó lần đầu tiên
Các giải pháp bị "khám phá lại" nhiều lần (Tôi từng giải quyết cùng một vấn đề CORS bốn lần trong sáu tháng)
Không có sự tích lũy kiến thức theo thời gian, cho cả bạn và trợ lý AI của bạn
Chi phí ẩn rất lớn. Nếu bạn chỉ dành 30 phút mỗi tuần để giải quyết lại các vấn đề bạn đã giải quyết, đó là 26 giờ mỗi năm. Với giá 100 đô la/giờ, đó là 2.600 đô la thời gian bị lãng phí cho mỗi nhà phát triển.
Nhưng nếu trợ lý AI của bạn có thể ghi nhớ thì sao?
Claude Code Agent Skill là gì?
Trước khi đi sâu vào project-memory, hãy hiểu rõ “skill” thực sự là gì.
Nếu bạn từng ước rằng mình có thể dạy cho Claude một workflow cụ thể hoặc cung cấp kiến thức chuyên môn cho một lĩnh vực nào đó, thì skills chính là giải pháp.
Một agent skill thực ra rất đơn giản:
Nó chỉ là một thư mục chứa một file SKILL.md cùng với một số tài nguyên hỗ trợ (nếu cần).
File SKILL.md gồm hai phần chính:
1. YAML Frontmatter
Phần metadata ở đầu file dùng để cho Claude biết khi nào nên kích hoạt skill này.
2. Markdown Body
Phần nội dung hướng dẫn — chứa các bước và quy tắc mà Claude sẽ làm theo khi skill được kích hoạt.
Cách hiểu đơn giản
Hãy nghĩ về skills như những “expert mode” có thể tái sử dụng mà bạn cài đặt cho AI.
Ví dụ:
Khi bạn nói “set up project memory”, Claude Code sẽ không đoán mò ý bạn muốn gì.
Thay vào đó, nó sẽ:
Tải skill tương ứng
Áp dụng bộ hướng dẫn đã được kiểm chứng
Thực hiện đúng workflow cho nhiệm vụ đó
Cấu trúc kỹ năng Agent Skill
Cấu trúc tập tin SKILL.md hiển thị phần đầu YAML với tên và mô tả, và phần thân Markdown với các phần Tổng quan, Khi nào nên sử dụng, Khả năng cốt lõi, Ví dụ và Tiêu chí thành công.
Các kỹ năng thường nằm ở hai vị trí:
Lưu trữ các kỹ năng trong thư mục chính của người dùng ~/.claude/skills/. Các kỹ năng này có sẵn trên toàn cầu trong tất cả các dự án và dành cho các kỹ năng đa năng như đánh giá mã, lập tài liệu. Sau đó, bạn có thể có các kỹ năng dành riêng cho dự án nằm trong .claude/skills/. Các kỹ năng này chỉ có hiệu lực cục bộ trong dự án này, dành riêng cho quy trình làm việc, quy ước nhóm. Tôi nói "thông thường" vì bạn có các kỹ năng cấp doanh nghiệp, các kỹ năng được chia sẻ ở cấp độ kho lưu trữ duy nhất, v.v. Và nó cũng phụ thuộc vào nhà cung cấp mà bạn đang sử dụng (~/.codex/skills/, ~/.config/opencode/skill/, ~/.gemini/skills/, .claude/skills/, .codex/skills/, .opencode/skills/, chỉ là một vài ví dụ).
Hãy thử cách này: Chạy lệnh `ls ~/.claude/skills/` để xem bạn đã cài đặt những kỹ năng nào. Nếu thư mục chưa tồn tại, bạn sẽ tạo nó khi cài đặt kỹ năng đầu tiên.
Sơ đồ kích hoạt skill thường gồm ba giai đoạn chính:
1. Discovery (Khám phá)
AI sẽ quét các thư mục chứa skill và chỉ đọc metadata của từng skill (tên + mô tả).
Ở bước này, nó không tải toàn bộ nội dung hướng dẫn.
2. Matching (So khớp)
AI kiểm tra xem yêu cầu của người dùng có khớp với skill nào không dựa trên metadata đã đọc.
3. Execution (Thực thi)
Khi tìm thấy skill phù hợp, AI mới:
tải toàn bộ file SKILL.md
đọc hướng dẫn chi tiết
và thực hiện tác vụ theo các bước đã định nghĩa
Insight quan trọng
Claude chỉ đọc metadata của skill trước, và chỉ tải đầy đủ hướng dẫn khi tìm được skill phù hợp.
Điều này có nghĩa là bạn có thể:
cài hàng chục thậm chí hàng trăm skills
mà không làm chậm các tương tác AI thông thường
Bây giờ khi đã hiểu cơ chế hoạt động của skills, chúng ta sẽ xem project-memory áp dụng cơ chế này như thế nào trong thực tế.
Cách thức kích hoạt kỹ năng hoạt động
Khi bạn đưa ra yêu cầu, Claude Code tuân theo mô hình tiết lộ dần dần để viết các kỹ năng cho agent. Nó chỉ tải những gì cần thiết, khi cần thiết. Điều này giúp tương tác nhanh chóng đồng thời cung cấp cho bạn quyền truy cập vào các khả năng mạnh mẽ khi cần.
Kỹ năng Quản lý Bộ nhớ Dự án
Kỹ năng quản lý bộ nhớ dự án tạo ra một hệ thống kiến thức có cấu trúc trong thư mục docs/project_notes/ với bốn tập tin chuyên dụng. Mỗi tập tin phục vụ một mục đích riêng biệt trong việc lưu giữ và truy xuất kiến thức dự án.
Cấu trúc Memory File
Hãy chú ý cấu trúc tệp bộ nhớ dự án, hiển thị thư mục docs/project_notes/ chứa các tệp bugs.md, decisions.md, key_facts.md và issues.md, cùng với các tệp cấu hình CLAUDE.md và AGENTS.md được liên kết với các tệp ghi chú dự án tạo nên bộ nhớ dự án.
Mỗi file memory trong hệ thống đều có một vai trò riêng để lưu trữ kiến thức của project.
Ví dụ, bugs.md hoạt động như một cơ sở dữ liệu bug có thể tìm kiếm.
Các entry như:
“BUG-018: Pulumi state drift — run pulumi refresh — yes”
không chỉ ghi lại vấn đề, mà còn cách giải quyết. Điều này giúp bạn không phải mất thời gian điều tra lại khi cùng một lỗi xuất hiện lần nữa. Tôi thường dùng file này để theo dõi những bug lặp lại trong project.
File decisions.md dùng để lưu các ADR (Architectural Decision Records) — tức các quyết định kiến trúc quan trọng. Ví dụ:
“ADR-012: Use D3.js for all charts (team expertise)”
Nhờ đó, team có thể duy trì sự nhất quán về công nghệ và tránh việc đưa ra các quyết định mâu thuẫn trong tương lai.
Trong khi đó, key_facts.md đóng vai trò như cheat sheet của project, lưu các thông tin quan trọng như:
“Staging API: https://api.staging.example.com:8443”
Điều này giúp loại bỏ việc phải đoán port, URL hay endpoint mỗi lần cần dùng.
Cuối cùng, issues.md hoạt động như một nhật ký công việc theo thời gian.
Ví dụ:
“TICKET-456: Implemented user auth — 2024-01-15”
File này tạo ra audit trail, giúp liên kết công việc đã hoàn thành với ticket và thời điểm thực hiện, từ đó dễ dàng truy vết lại lịch sử phát triển của project.
