| name | codebase-brain |
| version | 1.0.0 |
| description | Codebase second brain workflow for AI agents — use repo maps and capability maps before deep code reads |
| requires | [] |
| task_types | ["feature-implementation","bug-fix","refactoring","api-design"] |
| applies_to_tags | ["codebase-brain","backend","frontend","api"] |
Codebase Brain Skill
Mục tiêu
Giúp agent giảm thời gian re-discovery trong codebase bằng cách dùng codebase brain docs trước khi đọc sâu vào code.
Quy trình mặc định
Bước 1: Search repo-map và capability-map trước khi đọc code
Ngay khi nhận task:
- Gọi
POST /api/agent/search-docs với projectId của task.
- Ưu tiên
types: repo-map, capability-map, runbook, adr.
- Chỉ sau khi đã đọc các doc liên quan mới bắt đầu search code hoặc mở file lớn.
Ví dụ payload:
{
"query": "approval flow",
"projectId": "project-relayhq-aa6d7e",
"types": ["repo-map", "capability-map", "runbook", "adr"],
"agent_id": "agent-claude-code"
}
Cách dùng codebase brain docs
repo-map: hiểu cấu trúc thư mục, entrypoints, source of truth.capability-map: hiểu một luồng tính năng đi qua những route, service, store, component hoặc test nào.runbook: hiểu các bước thao tác hoặc debug flow.adr: hiểu vì sao kiến trúc hiện tại được chọn.
Khi nào cần search gì
- Nếu task nói về một feature hoặc workflow: search
capability-map trước.
- Nếu task nói về một module hoặc codebase chưa quen: search
repo-map trước.
- Nếu task chạm behavior vận hành hoặc quy trình: search
runbook.
- Nếu task có vẻ đi ngược kiến trúc hiện tại: search
adr trước khi sửa.
Sau khi sửa code
Khi thay đổi làm dịch chuyển hiểu biết về codebase, agent phải cập nhật hoặc tạo docs liên quan.
Nên update docs khi:
- xuất hiện file source of truth mới
- luồng capability đổi đường đi
- checklist thay đổi feature đã khác trước
- có quyết định kiến trúc mới hoặc rule mới đáng tái sử dụng
Nguyên tắc thực thi
- Dùng docs để định hướng.
- Dùng code search để khoanh vùng.
- Chỉ đọc file đích sau khi đã có bản đồ.
- Nếu phát hiện doc sai hoặc cũ, sửa doc như một phần của task hoặc tạo follow-up rõ ràng.
