Prompt Agent | prompts.chat

Văn bản

Câu lệnh này hướng dẫn các tác nhân AI tạo một bản hồ sơ ngữ cảnh (context artifact) toàn diện nhằm bảo toàn toàn bộ ngữ cảnh hội thoại, tiến độ công việc, các quyết định đã đưa ra và cấu trúc dự án. Nó cho phép tiếp nối công việc liền mạch giữa các phiên làm việc AI, các nền tảng hoặc các tác nhân khác nhau, đóng vai trò như một chiếc "USB lưu trữ ngữ cảnh" giúp ngăn chặn việc phải giải thích lại từ đầu hoặc mất mát thông tin. xem câu lệnh phụ (sub-prompt) cho luồng quy trình làm việc khác


# Câu Lệnh Bảo Toàn & Di Chuyển Ngữ Cảnh (Context Preservation & Migration Prompt)

[ for AGENT.MD pass THE `## SECTION` if NOT APPLICABLE ]

Hãy tạo một hồ sơ ngữ cảnh (context artifact) toàn diện giúp bảo toàn toàn bộ ngữ cảnh hội thoại, tiến độ công việc, các quyết định và cấu trúc dự án để tiếp tục công việc một cách liền mạch giữa các phiên làm việc AI, các nền tảng hoặc các tác nhân (agents) khác nhau. Hồ sơ này đóng vai trò như một chiếc "USB ngữ cảnh" giúp bất kỳ AI nào cũng có thể ngay lập tức nắm bắt tình hình và tiếp tục công việc mà không cần lặp lại hay bị đứt gãy ngữ cảnh.

## Các Mục Tiêu Cốt Lõi

Thu thập và cấu trúc hóa toàn bộ các yếu tố ngữ cảnh từ phiên làm việc hiện tại nhằm cho phép:
1. **Duy Trì Tính Liên Tục Của Phiên (Session Continuity)** - Tiếp tục cuộc trò chuyện trên các nền tảng AI khác nhau mà không cần giải thích lại từ đầu
2. **Bàn Giao Giữa Các Tác Nhân (Agent Handoff)** - Chuyển giao các tác vụ đang dang dở cho các tác nhân mới kèm theo tài liệu ghi nhận tiến độ đầy đủ
3. **Di Chuyển Dự Án (Project Migration)** - Sao chép toàn bộ văn hóa làm việc của dự án, quy trình (workflows) và cấu trúc quản trị

## Các Danh Mục Nội Dung Cần Bảo Toàn

### Ngữ Cảnh Hội Thoại (Conversational Context)
- Các yêu cầu ban đầu và câu chuyện người dùng (user stories) được phát triển qua trao đổi
- Các ý tưởng được khởi tạo trong những phiên động não (brainstorming)
- Các quyết định đã đưa ra kèm theo chuỗi lý giải nguyên nhân đầy đủ
- Các thỏa thuận đã đạt được và trạng thái xác nhận của chúng
- Các đề xuất và khuyến nghị kèm theo ngữ cảnh bổ trợ
- Các giả định đã thiết lập và trạng thái hiệu lực hiện tại của chúng
- Các góc nhìn sâu sắc (key insights) và những khoảnh khắc đột phá
- Các điểm mấu chốt đóng vai trò là nền tảng cấu trúc

### Tài Liệu Hóa Tiến Độ (Progress Documentation)
- Trạng thái hiện tại của tất cả các luồng công việc (work streams)
- Các tác vụ và sản phẩm bàn giao đã hoàn thành
- Các hạng mục đang chờ xử lý và các bước tiếp theo
- Các điểm nghẽn (blockers) gặp phải kèm chiến lược giảm thiểu/tháo gỡ
- Các giới hạn tốc độ (rate limits) đã chạm phải và giải pháp khắc phục tạm thời
- Dòng thời gian của các cột mốc quan trọng

### Kiến Trúc Dự Án (khi áp dụng)
- Phương pháp luận SDLC và các giai đoạn phát triển
- Hệ sinh thái tác nhân (tác nhân chính, tác nhân phụ, tác nhân ngang hàng, tác nhân quan sát giám sát)
- Các quy tắc, chính sách quản trị và chiến lược
- Cấu trúc kho lưu trữ mã nguồn (.github workflows, các mẫu templates)
- Các biểu mẫu câu lệnh tái sử dụng (phân rã epic, PRD, kế hoạch kiến trúc, thiết kế hệ thống)
- Các mẫu quy ước chuẩn (định dạng commit, câu lệnh bộ nhớ memory prompts, cấu trúc ghi log)
- Phân cấp hướng dẫn (các biến thể ở cấp dự án, cấp sprint, cấp epic)
- Cấu hình CI/CD (kiểm thử, định dạng mã, trích xuất commit)
- Điều phối đa tác nhân (nối chuỗi câu lệnh prompt chaining, chạy song song, tác nhân định tuyến router agents)
- Tiêu chuẩn định dạng đầu ra và các biến thể

### Quy Tắc & Giao Thức (Rules & Protocols)
- Các nguyên tắc hướng dẫn đã thiết lập kèm định nghĩa phạm vi áp dụng
- Các chỉ dẫn bổ sung được thêm vào trong suốt phiên làm việc
- Các ràng buộc và ranh giới đã đặt ra
- Tiêu chuẩn chất lượng và tiêu chí nghiệm thu (acceptance criteria)
- Cơ chế căn chỉnh nhằm giữ cho công việc luôn đi đúng quỹ đạo

# Các Bước Thực Hiện

1. **Quét Lịch Sử Hội Thoại** - Rà soát toàn bộ luồng trò chuyện/phiên làm việc để nắm bắt mọi tương tác và ngữ cảnh
2. **Trích Xuất Các Yếu Tố Cốt Lõi** - Xác định và phân loại thông tin theo các danh mục nội dung nêu trên
3. **Lập Tài Liệu Trạng Thái Tiến Độ** - Ghi nhận rõ những gì đã hoàn thành, đang thực hiện và đang chờ xử lý
4. **Bảo Toàn Chuỗi Quyết Định** - Đưa vào lý do đằng sau tất cả các lựa chọn quan trọng
5. **Cấu Trúc Hóa Để Dễ Di Chuyển** - Sắp xếp theo định dạng chuẩn mà mọi hệ thống đều có thể đọc hiểu
6. **Thêm Hướng Dẫn Bàn Giao** - Bao gồm hướng dẫn tường minh dành cho AI/tác nhân/phiên làm việc tiếp theo

# Định Dạng Đầu Ra

Tạo một tài liệu markdown có cấu trúc gồm các phần sau:

```
# CONTEXT ARTIFACT: [Session/Project Title]
**Generated**: [Date/Time]
**Source Platform**: [AI Platform Name]
**Continuation Priority**: [Critical/High/Medium/Low]

## SESSION OVERVIEW
[2-3 sentence summary of primary goals and current state]

## CORE CONTEXT
### Original Requirements
[Initial user requests and goals]

### Evolution & Decisions
[Key decisions made, with rationale - bulleted list]

### Current Progress
- Completed: [List]
- In Progress: [List with % complete]
- Pending: [List]
- Blocked: [List with blockers and mitigations]

## KNOWLEDGE BASE
### Key Insights & Agreements
[Critical discoveries and consensus points]

### Established Rules & Protocols
[Guidelines, constraints, standards set during session]

### Assumptions & Validations
[What's been assumed and verification status]

## ARTIFACTS & DELIVERABLES
[List of files, documents, code created with descriptions]

## PROJECT STRUCTURE (if applicable)
### Architecture Overview
[SDLC, workflows, repository structure]

### Agent Ecosystem
[Description of agents, their roles, interactions]

### Reusable Components
[Prompt templates, workflows, automation scripts]

### Governance & Standards
[Instructions hierarchy, conventional patterns, quality gates]

## HANDOFF INSTRUCTIONS
### For Next Session/Agent
[Explicit steps to continue work]

### Context to Emphasize
[What the next AI must understand immediately]

### Potential Challenges
[Known issues and recommended approaches]

## CONTINUATION QUERY
[Suggested prompt for next AI: "Given this context artifact, please continue by..."]
```

# Các Ví Dụ

**Ví dụ 1: Duy Trì Tính Liên Tục Của Phiên (Bàn Giao Phiên Động Não)**

Đầu vào: "Chúng ta đã động não về một ứng dụng di động suốt 2 tiếng rồi. Giờ tôi cần chuyển sang dùng Claude. Hãy tạo hồ sơ ngữ cảnh."

Đầu ra:
```
# CONTEXT ARTIFACT: FitTrack Mobile App Planning
**Generated**: 2026-01-07 14:30
**Source Platform**: Google Gemini
**Continuation Priority**: High

## SESSION OVERVIEW
Đã động não ý tưởng ứng dụng di động theo dõi thể chất dành cho giới chuyên gia bận rộn. Quyết định chọn thiết kế tối giản tích hợp huấn luyện viên AI. Sẵn sàng bước sang giai đoạn thiết kế kiến trúc kỹ thuật.

## CORE CONTEXT
### Original Requirements
- Người dùng mục tiêu: Người đi làm chuyên nghiệp từ 25-40 tuổi, có ít thời gian đến phòng tập
- Bắt buộc đồng bộ với Apple Watch và Fitbit
- Ngân sách: $50k cho bản MVP
- Tiến độ: 3 tháng để ra mắt

### Evolution & Decisions
- ✓ Tên gọi: "FitTrack Pro" (đã loại: "QuickFit", "PowerHour")
- ✓ Tính năng cốt lõi: Các bài tập 15 phút được cá nhân hóa bằng AI (không dùng giáo án đại trà)
- ✓ Mô hình kiếm tiền: Freemium (gói cao cấp $9.99/tháng)
- ✓ Ngăn xếp công nghệ: React Native (phát triển đồng thời cho cả iOS+Android)

### Current Progress
- Completed: Phân loại ưu tiên tính năng, chân dung người dùng (user personas), mô hình doanh thu
- In Progress: Chưa bắt đầu
- Pending: Kiến trúc kỹ thuật, lược đồ cơ sở dữ liệu (database schema), thiết kế API
- Blocked: Không có

## KNOWLEDGE BASE
### Key Insights & Agreements
- Người dùng muốn "ngắn gọn thông minh" hơn là "dài dòng đầy đủ" - sự cô đọng chính là tính năng cao cấp
- Huấn luyện viên AI phải mang lại cảm giác trò chuyện tự nhiên, không ra lệnh cứng nhắc như máy móc
- Các tính năng mạng xã hội được lùi sang bản v2 để tránh phình to phạm vi dự án (scope creep)

(... phần còn lại của cấu trúc tiếp tục bên dưới)

## CONTINUATION QUERY
"Dựa trên hồ sơ ngữ cảnh lập kế hoạch ứng dụng FitTrack Pro này, vui lòng thiết kế kiến trúc kỹ thuật bao gồm lược đồ cơ sở dữ liệu, các API endpoints và chiến lược tích hợp bên thứ ba cho Apple Watch và Fitbit."
```

**Ví dụ 2: Bàn Giao Giữa Các Tác Nhân (Tác Vụ Tự Động Hóa Chạm Giới Hạn Tốc Độ)**

Đầu vào: "Tác nhân trình duyệt (Browser agent) đã chạm giới hạn tốc độ khi đang thu thập dữ liệu giá của đối thủ. Hãy tạo tài liệu bàn giao."

Đầu ra:
```
# CONTEXT ARTIFACT: Competitor Pricing Automation (Incomplete)
**Generated**: 2026-01-07 09:15
**Source Platform**: Browser Agent v2.1
**Continuation Priority**: Critical

## SESSION OVERVIEW
Thu thập dữ liệu tự động trên 50 trang web của đối thủ cạnh tranh để so sánh giá. Đã hoàn thành 32/50 trang trước khi bị chặn giới hạn tốc độ (rate limiting). Cần tiếp tục ngay lập tức để kịp hạn chót vào Thứ Sáu.

## CORE CONTEXT
### Original Requirements
- Thu thập giá mặt hàng "tai nghe không dây dưới $100" từ 50 trang thương mại điện tử
- Trích xuất: tên sản phẩm, giá, điểm đánh giá, số lượng nhận xét
- Đầu ra: Một tệp CSV duy nhất để phân tích
- Hạn chót: 5 giờ chiều Thứ Sáu

### Evolution & Decisions
- ✓ Đã thêm logic thử lại (retry) sau những lần thất bại ban đầu trên các trang web dùng nhiều JS
- ✓ Đã chuyển sang dùng headless Chrome (thay vì thư viện requests) để tương thích tốt hơn
- ✓ Đã áp dụng độ trễ 3 giây giữa các yêu cầu trên mỗi tên miền
- ✓ Người dùng đã thêm chỉ dẫn: "Bỏ qua các trang web bắt buộc đăng nhập"

### Current Progress
- Completed: Đã thu thập thành công 32/50 trang web (2,847 sản phẩm)
- In Progress: Không có (đã tạm dừng tại thời điểm chạm giới hạn tốc độ)
- Pending: Còn lại 18 trang web (danh sách nằm trong mục "Continuation Query" bên dưới)
- Blocked: Bị giới hạn tốc độ trên các tên miền: amazon.com, walmart.com, target.com (cần chờ hạ nhiệt 2 giờ)

## KNOWLEDGE BASE
### Established Rules & Protocols
- Tuân thủ nghiêm ngặt tệp robots.txt không có ngoại lệ
- Tối đa 1 yêu cầu mỗi 3 giây trên từng tên miền
- Bỏ qua các sản phẩm không có đánh giá nào (gây nhiễu dữ liệu)
- Xử lý phân trang tối đa đến 5 trang cho mỗi website

### Challenges & Mitigations
- Thách thức: Giá biến động linh hoạt (thay đổi ngay trong quá trình thu thập)
  Giải pháp: Gắn nhãn thời gian (timestamp) cho từng bản ghi
- Thách thức: Mã xác thực chống bot CAPTCHA trên 3 trang web
  Giải pháp: Người dùng đã đồng ý tự nhập dữ liệu thủ công cho 3 trang này
- Thách thức: Bị giới hạn tốc độ truy cập (Rate limiting)
  Giải pháp: Triển khai thời gian chờ tăng dần theo cấp số nhân (exponential backoff), xoay vòng chuỗi định danh trình duyệt (user agents)

## CONTINUATION QUERY
"Tiếp tục quy trình tự động hóa thu thập dữ liệu giá. Còn lại 18 trang web: [bestbuy.com, newegg.com, ebay.com...]. Sử dụng tệp CSV hiện có 'pricing_data_partial.csv' (2,847 bản ghi). Các tên miền bị giới hạn tốc độ cần chờ đủ 2 giờ. Ưu tiên chạy các trang không bị chặn trước. Áp dụng toàn bộ các quy tắc đã thiết lập: độ trễ 3 giây, bỏ qua sản phẩm không có đánh giá, giới hạn phân trang 5 trang. Bàn giao tệp CSV hoàn chỉnh trước 5 giờ chiều Thứ Sáu."
```

**Ví dụ 3: Di Chuyển Dự Án (Chuyển Giao Toàn Bộ Văn Hóa Làm Việc)**

(Ngữ cảnh đầu vào: Toàn bộ kho lưu trữ dự án bao gồm SDLC, hệ thống tác nhân và cơ chế quản trị)

Đầu ra: *(Ví dụ rút gọn thể hiện cấu trúc - kết quả thực tế sẽ chi tiết và toàn diện hơn)*
```
# CONTEXT ARTIFACT: "SmartInventory" Project Culture & Architecture
**Generated**: 2026-01-07 16:00
**Source Platform**: GitHub Copilot + Multi-Agent System
**Continuation Priority**: Medium (tích hợp sang khung tác nhân AI mới)

## SESSION OVERVIEW
Hệ thống quản lý kho hàng cấp doanh nghiệp sử dụng văn hóa phát triển phần mềm dẫn dắt bởi AI. Cần tái tạo toàn bộ cấu trúc dự án, hệ sinh thái tác nhân và cơ chế quản trị cho thiết lập tác nhân AI tự hành mới.

## PROJECT STRUCTURE
### SDLC Framework
- Phương pháp luận: Agile với các sprint kéo dài 2 tuần
- Các giai đoạn: Lập kế hoạch Epic → Phát triển → Tác nhân Quan sát Đánh giá → CI/CD → Triển khai
- Mọi hoạt động đều do AI thực hiện: sinh mã nguồn, kiểm thử, viết tài liệu, tạo mạch chuyện giải thích cho các bản commit

### Agent Ecosystem
**Các Tác Nhân Chính (Main Agents):**
- DevAgent: Sinh mã nguồn và triển khai tính năng
- TestAgent: Kiểm thử tự động và đảm bảo chất lượng
- DocAgent: Khởi tạo và duy trì tài liệu

**Tác Nhân Quan Sát - Observer Agent (Người Bảo Vệ Dự Án):**
- Vai trò: Thực thi việc căn chỉnh chuẩn mực xuyên suốt tất cả các tác nhân
- Chức năng: Phản hồi đánh giá PR, xác thực đường dẫn, kiểm tra tuân thủ tiêu chuẩn
- Điều kiện kích hoạt: Mỗi lần commit, tạo PR và khi hoàn thành một epic

**Các Tác Nhân CI/CD:**
- FormatterAgent: Thực thi quy chuẩn định dạng mã nguồn
- ReflectionAgent: Trích xuất các bản commit → tổng hợp thành bài chiêm nghiệm có cấu trúc, mạch chuyện phát triển và báo cáo tường thuật
- DeployAgent: Các đường ống triển khai tự động

**Các Tác Nhân Phụ - Sub-Agents (chia theo miền tính năng):**
- InventorySubAgent, UserAuthSubAgent, ReportingSubAgent

**Điều Phối (Orchestration):**
- Phối hợp đa tác nhân thông qua các tệp sổ tay .ipynb
- Các mẫu điều phối: Nối chuỗi câu lệnh (Prompt chaining), thực thi song song, tác nhân định tuyến (router agents)

### Repository Structure (.github)
```
.github/
├── workflows/
│   ├── epic_breakdown.yml
│   ├── epic_generator.yml
│   ├── prd_template.yml
│   ├── architectural_plan.yml
│   ├── system_design.yml
│   ├── conventional_commit.yml
│   ├── memory_prompt.yml
│   └── log_prompt.yml
├── AGENTS.md (danh bạ đăng ký tác nhân)
├── copilot-instructions.md (quy tắc cấp độ toàn dự án)
└── sprints/
    ├── sprint_01_instructions.md
    └── epic_variations/
```

### Governance & Standards
**Phân Cấp Hướng Dẫn (Instructions Hierarchy):**
1. `copilot-instructions.md` - Các quy tắc bất biến áp dụng trên toàn dự án
2. Hướng dẫn theo Sprint - Các biến thể theo từng giai đoạn thời gian của mỗi sprint
3. Hướng dẫn theo Epic - Các chỉ dẫn gọi thực thi gắn với mục tiêu cụ thể

**Các Mẫu Quy Ước Chuẩn (Conventional Patterns):**
- Commits: `type(scope): description` tuân theo đặc tả Conventional Commits
- Câu lệnh bộ nhớ (Memory prompt): Mẫu bảo toàn trạng thái phiên làm việc
- Câu lệnh ghi nhật ký (Log prompt): Định dạng theo dõi hoạt động có cấu trúc

(... các phần tiếp theo: Thành phần Tái sử dụng, Cổng Kiểm soát Chất lượng, Hướng dẫn Tiếp tục để dựng lại hệ thống với các tác nhân AI mới...)
```

# Ghi Chú Quan Trọng

- **Tính Phổ Quát (Universality)**: Cấu trúc phải dễ dàng được đọc hiểu bởi bất kỳ nền tảng AI nào (ChatGPT, Claude, Gemini, v.v.)
- **Sự Đầy Đủ so với Tính Ngắn Gọn**: Cân bằng giữa việc lưu giữ ngữ cảnh toàn diện và khả năng đọc lướt dễ dàng - sử dụng các phần lồng nhau cho những chi tiết sâu
- **Kiểm Soát Phiên Bản**: Đưa vào nhãn thời gian và tên nền tảng nguồn để theo dõi sự tiến hóa của ngữ cảnh qua nhiều lần bàn giao liên tiếp
- **Định Hướng Hành Động**: Luôn kết thúc bằng mục "Continuation Query" rõ ràng - câu lệnh chính xác để sao chép cho AI tiếp theo sử dụng ngay
- **Thích Ứng Theo Quy Mô Dự Án**: Đối với việc di chuyển toàn bộ dự án (Trường hợp 3), hãy mở rộng đáng kể phần "Project Structure" trong khi giữ các phần khác súc tích
- **Ghi Nhận Các Thất Bại**: Ghi lại rõ ràng những cách làm nào đã không hiệu quả và lý do tại sao - điều này ngăn AI tiếp theo lặp lại vết xe đổ
- **Bảo Toàn Quy Tắc**: Khi các quy tắc/giao thức được thiết lập trong phiên làm việc, hãy kèm theo ngữ cảnh giải thích TẠI SAO chúng lại cần thiết
- **Xác Thực Giả Định**: Đánh dấu rõ các giả định là "đã xác thực (validated)", "đang chờ xác thực (pending validation)", hoặc "đã bác bỏ (invalidated)" để đảm bảo sự minh bạch

- - DÀNH CHO GEMINI / GEMINI-CLI / ANTIGRAVITY

Dưới đây là các phiên bản siêu cô đọng:

GEMINI.md
"# Tác nhân AI Gemini đa nền tảng

workflow/agent/sample.toml
"# mẫu câu lệnh antigravity


MEMORY.md
"# Bộ nhớ Gemini

**Session**: 2026-01-07 | Sprint 01 (còn 7 ngày) | Epic EPIC-001 (45%)  
**Active**: TASK-001-03 API CRUD kho hàng (GET/POST đã xong, PUT/DELETE đang chờ)  
**Decisions**: PostgreSQL + JSONB, RESTful /api/v1/, kiểm thử bằng pytest  
**Next**: Hoàn thiện các endpoint PUT/DELETE, chốt lược đồ cơ sở dữ liệu"

Agent Prompt Engineering Product Management

J@joembolinas

Trình Xây Dựng Máy Chủ MCP (MCP Builder)

Kỹ năng

Hướng dẫn tạo các máy chủ MCP (Model Context Protocol) chất lượng cao giúp các mô hình ngôn ngữ lớn (LLM) tương tác với các dịch vụ bên ngoài thông qua các công cụ được thiết kế bài bản. Sử dụng khi xây dựng máy chủ MCP để tích hợp các API hoặc dịch vụ bên ngoài, dù bằng Python (FastMCP) hay Node/TypeScript (MCP SDK).

---
name: mcp-builder
description: Hướng dẫn tạo các máy chủ MCP (Model Context Protocol) chất lượng cao giúp các mô hình ngôn ngữ lớn (LLM) tương tác với các dịch vụ bên ngoài thông qua các công cụ được thiết kế bài bản. Sử dụng khi xây dựng máy chủ MCP để tích hợp các API hoặc dịch vụ bên ngoài, dù bằng Python (FastMCP) hay Node/TypeScript (MCP SDK).
license: Complete terms in LICENSE.txt
---

# Hướng Dẫn Phát Triển Máy Chủ MCP (MCP Server Development Guide)

## Tổng Quan

Tạo các máy chủ MCP (Model Context Protocol - Giao thức Ngữ cảnh Mô hình) cho phép các LLM tương tác với những dịch vụ bên ngoài thông qua các công cụ (tools) được thiết kế bài bản. Chất lượng của một máy chủ MCP được đo lường bằng mức độ hiệu quả mà nó giúp các LLM hoàn thành những tác vụ thực tế.

---

# Quy Trình Thực Hiện

## 🚀 Luồng Công Việc Tổng Quan

Việc tạo ra một máy chủ MCP chất lượng cao bao gồm bốn giai đoạn chính:

### Giai Đoạn 1: Nghiên Cứu Chuyên Sâu và Lập Kế Hoạch

#### 1.1 Hiểu Thiết Kế MCP Hiện Đại

**Độ Bao Phủ API so với Công Cụ Theo Luồng Công Việc (Workflow Tools):**
Cân bằng giữa việc bao phủ toàn diện các điểm cuối (endpoints) của API với các công cụ chuyên biệt theo luồng công việc. Các công cụ theo luồng công việc có thể tiện lợi hơn cho những tác vụ cụ thể, trong khi độ bao phủ API toàn diện mang lại cho tác tử (agents) sự linh hoạt để tự kết hợp các thao tác với nhau. Hiệu năng sẽ khác nhau tùy theo từng trình khách (client)—một số trình khách hưởng lợi từ khả năng thực thi mã nguồn kết hợp các công cụ cơ bản, trong khi những trình khách khác lại hoạt động tốt hơn với các luồng công việc cấp cao. Khi chưa chắc chắn, hãy ưu tiên độ bao phủ API toàn diện.

**Đặt Tên Công Cụ và Khả Năng Dễ Tìm Kiếm:**
Tên công cụ rõ ràng, giàu tính mô tả sẽ giúp tác tử tìm thấy đúng công cụ cần dùng một cách nhanh chóng. Hãy sử dụng các tiền tố nhất quán (ví dụ: `github_create_issue`, `github_list_repos`) và đặt tên theo hướng hành động.

**Quản Lý Ngữ Cảnh (Context Management):**
Các tác tử làm việc hiệu quả hơn khi mô tả công cụ ngắn gọn súc tích và có khả năng lọc/phân trang (filter/paginate) kết quả trả về. Hãy thiết kế các công cụ trả về dữ liệu có trọng tâm và thực sự liên quan. Một số trình khách hỗ trợ thực thi mã nguồn có thể giúp tác tử tự lọc và xử lý dữ liệu một cách hiệu quả.

**Thông Báo Lỗi Có Tính Hành Động:**
Thông báo lỗi cần hướng dẫn tác tử tìm ra hướng giải quyết kèm theo các gợi ý cụ thể và bước tiếp theo cần làm.

#### 1.2 Nghiên Cứu Tài Liệu Giao Thức MCP

**Duyệt đặc tả kỹ thuật MCP:**

Bắt đầu từ sơ đồ trang web (sitemap) để tìm các trang có liên quan: `https://modelcontextprotocol.io/sitemap.xml`

Sau đó truy xuất các trang cụ thể với hậu tố `.md` để lấy định dạng markdown (ví dụ: `https://modelcontextprotocol.io/specification/draft.md`).

Các trang quan trọng cần xem xét:
- Tổng quan đặc tả kỹ thuật và kiến trúc hệ thống
- Các cơ chế truyền tải (streamable HTTP, stdio)
- Định nghĩa về công cụ (tool), tài nguyên (resource) và lời nhắc mẫu (prompt)

#### 1.3 Nghiên Cứu Tài Liệu Framework

**Ngăn xếp công nghệ khuyên dùng:**
- **Ngôn ngữ**: TypeScript (hỗ trợ SDK chất lượng cao và khả năng tương thích tốt trong nhiều môi trường thực thi, ví dụ như MCPB. Hơn nữa, các mô hình AI rất giỏi sinh mã TypeScript nhờ mức độ phổ biến rộng rãi, hệ thống kiểu tĩnh và các công cụ kiểm tra mã nguồn linting tốt)
- **Phương thức truyền tải (Transport)**: Streamable HTTP cho các máy chủ từ xa, sử dụng JSON phi trạng thái (stateless JSON — đơn giản hơn để mở rộng quy mô và bảo trì so với các phiên có trạng thái và phản hồi phân luồng phức tạp). Dùng stdio cho các máy chủ chạy cục bộ.

**Tải tài liệu hướng dẫn framework:**

- **Thực hành Tốt nhất về MCP**: [📋 Xem Thực Hành Tốt Nhất](./reference/mcp_best_practices.md) - Các nguyên tắc cốt lõi

**Đối với TypeScript (khuyên dùng):**
- **TypeScript SDK**: Sử dụng WebFetch để tải `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
- [⚡ Hướng Dẫn TypeScript](./reference/node_mcp_server.md) - Các mẫu thiết kế và ví dụ bằng TypeScript

**Đối với Python:**
- **Python SDK**: Sử dụng WebFetch để tải `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`
- [🐍 Hướng Dẫn Python](./reference/python_mcp_server.md) - Các mẫu thiết kế và ví dụ bằng Python

#### 1.4 Lập Kế Hoạch Triển Khai

**Tìm hiểu API:**
Xem xét tài liệu API của dịch vụ cần tích hợp để xác định các điểm cuối chính, yêu cầu xác thực và mô hình dữ liệu. Sử dụng công cụ tìm kiếm web và WebFetch khi cần thiết.

**Lựa Chọn Công Cụ:**
Ưu tiên độ bao phủ API toàn diện. Liệt kê danh sách các điểm cuối cần triển khai, bắt đầu từ những thao tác phổ biến nhất.

---

### Giai Đoạn 2: Triển Khai Mã Nguồn (Implementation)

#### 2.1 Thiết Lập Cấu Trúc Dự Án

Xem các hướng dẫn dành riêng cho từng ngôn ngữ để thiết lập dự án:
- [⚡ Hướng Dẫn TypeScript](./reference/node_mcp_server.md) - Cấu trúc dự án, package.json, tsconfig.json
- [🐍 Hướng Dẫn Python](./reference/python_mcp_server.md) - Tổ chức module, các thư viện phụ thuộc

#### 2.2 Triển Khai Hạ Tầng Cốt Lõi

Tạo các tiện ích dùng chung:
- Trình khách gọi API (API client) kèm cơ chế xác thực
- Các hàm hỗ trợ xử lý lỗi
- Định dạng phản hồi đầu ra (JSON/Markdown)
- Hỗ trợ phân trang (pagination)

#### 2.3 Triển Khai Các Công Cụ (Tools)

Đối với mỗi công cụ:

**Lược đồ Đầu vào (Input Schema):**
- Sử dụng Zod (TypeScript) hoặc Pydantic (Python)
- Đưa vào các ràng buộc dữ liệu và phần mô tả rõ ràng
- Bổ sung ví dụ minh họa ngay trong phần mô tả trường dữ liệu

**Lược đồ Đầu ra (Output Schema):**
- Định nghĩa `outputSchema` ở những nơi có thể cho dữ liệu có cấu trúc
- Sử dụng `structuredContent` trong phản hồi của công cụ (tính năng của TypeScript SDK)
- Giúp các trình khách hiểu và xử lý đầu ra của công cụ dễ dàng hơn

**Mô Tả Công Cụ (Tool Description):**
- Tóm tắt ngắn gọn chức năng của công cụ
- Mô tả chi tiết các tham số
- Lược đồ kiểu dữ liệu trả về

**Cài Đặt Logic (Implementation):**
- Sử dụng Async/await cho các thao tác I/O
- Xử lý lỗi đúng chuẩn kèm thông báo có hướng dẫn hành động cụ thể
- Hỗ trợ phân trang ở những nơi phù hợp
- Trả về cả nội dung văn bản lẫn dữ liệu có cấu trúc khi sử dụng các bộ SDK hiện đại

**Chú Giải Công Cụ (Annotations):**
- `readOnlyHint`: true/false
- `destructiveHint`: true/false
- `idempotentHint`: true/false
- `openWorldHint`: true/false

---

### Giai Đoạn 3: Rà Soát và Kiểm Thử

#### 3.1 Chất Lượng Mã Nguồn

Rà soát để đảm bảo:
- Không có mã nguồn bị lặp lại (nguyên tắc DRY)
- Xử lý lỗi nhất quán trên toàn bộ công cụ
- Bao phủ kiểu dữ liệu đầy đủ (full type coverage)
- Mô tả công cụ rõ ràng, dễ hiểu

#### 3.2 Biên Dịch và Kiểm Thử

**TypeScript:**
- Chạy `npm run build` để kiểm tra xác minh quá trình biên dịch
- Kiểm thử bằng công cụ MCP Inspector: `npx @modelcontextprotocol/inspector`

**Python:**
- Kiểm tra cú pháp: `python -m py_compile your_server.py`
- Kiểm thử bằng MCP Inspector

Xem hướng dẫn riêng của từng ngôn ngữ để biết phương pháp kiểm thử chi tiết và danh sách kiểm tra chất lượng.

---

### Giai Đoạn 4: Xây Dựng Bộ Đánh Giá (Evaluations)

Sau khi triển khai xong máy chủ MCP, hãy tạo bộ đánh giá toàn diện để kiểm tra mức độ hiệu quả thực tế của nó.

**Tải [✅ Hướng Dẫn Đánh Giá](./reference/evaluation.md) để xem toàn bộ nguyên tắc xây dựng bài đánh giá.**

#### 4.1 Hiểu Mục Đích Của Việc Đánh Giá

Sử dụng các bài đánh giá để kiểm tra xem LLM có thể sử dụng máy chủ MCP của bạn một cách hiệu quả nhằm trả lời những câu hỏi thực tế, phức tạp hay không.

#### 4.2 Tạo 10 Câu Hỏi Đánh Giá

Để tạo ra các bài đánh giá hiệu quả, hãy làm theo quy trình được nêu trong tài liệu hướng dẫn đánh giá:

1. **Khảo sát Công cụ (Tool Inspection)**: Liệt kê các công cụ hiện có và nắm rõ năng lực của chúng
2. **Khám phá Nội dung (Content Exploration)**: Sử dụng các thao tác CHỈ ĐỌC (READ-ONLY) để khám phá dữ liệu thực tế hiện có
3. **Khởi tạo Câu hỏi (Question Generation)**: Tạo 10 câu hỏi phức tạp, sát với thực tế
4. **Xác minh Câu trả lời (Answer Verification)**: Tự mình giải từng câu hỏi để xác minh đáp án chính xác

#### 4.3 Yêu Cầu Đối Với Bài Đánh Giá

Đảm bảo mỗi câu hỏi phải thỏa mãn các tiêu chí:
- **Độc lập (Independent)**: Không phụ thuộc vào kết quả của các câu hỏi khác
- **Chỉ đọc (Read-only)**: Chỉ yêu cầu các thao tác truy vấn không làm thay đổi hay phá hủy dữ liệu
- **Phức tạp (Complex)**: Đòi hỏi phải gọi nhiều công cụ kết hợp và khám phá dữ liệu sâu
- **Thực tế (Realistic)**: Dựa trên các trường hợp sử dụng thực tế mà con người thực sự quan tâm
- **Có thể kiểm chứng (Verifiable)**: Có một đáp án duy nhất, rõ ràng, có thể kiểm chứng bằng phép so sánh chuỗi
- **Ổn định (Stable)**: Đáp án sẽ không bị thay đổi theo thời gian

#### 4.4 Định Dạng Đầu Ra

Tạo một tệp XML theo cấu trúc sau:

```xml
<evaluation>
  <qa_pair>
    <question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation that uses the format ASL-X. What number X was being determined for the model named after a spotted wild cat?</question>
    <answer>3</answer>
  </qa_pair>
<!-- More qa_pairs... -->
</evaluation>
```

---

# Các Tệp Tài Liệu Tham Khảo

## 📚 Thư Viện Tài Liệu

Tải các tài nguyên này khi cần thiết trong suốt quá trình phát triển:

### Tài Liệu MCP Cốt Lõi (Tải Đầu Tiên)
- **Giao thức MCP (MCP Protocol)**: Bắt đầu với sơ đồ trang tại `https://modelcontextprotocol.io/sitemap.xml`, sau đó truy xuất các trang cụ thể kèm hậu tố `.md`
- [📋 Thực Hành Tốt Nhất Về MCP](./reference/mcp_best_practices.md) - Các nguyên tắc MCP phổ quát bao gồm:
  - Quy ước đặt tên máy chủ và công cụ
  - Hướng dẫn định dạng phản hồi (JSON so với Markdown)
  - Thực hành tốt nhất về phân trang
  - Lựa chọn phương thức truyền tải (streamable HTTP so với stdio)
  - Tiêu chuẩn bảo mật và xử lý lỗi

### Tài Liệu SDK (Tải Trong Giai Đoạn 1/2)
- **Python SDK**: Truy xuất từ `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`
- **TypeScript SDK**: Truy xuất từ `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`

### Hướng Dẫn Triển Khai Theo Từng Ngôn Ngữ (Tải Trong Giai Đoạn 2)
- [🐍 Hướng Dẫn Triển Khai Python](./reference/python_mcp_server.md) - Hướng dẫn toàn diện về Python/FastMCP bao gồm:
  - Các mẫu khởi tạo máy chủ
  - Ví dụ về mô hình Pydantic
  - Đăng ký công cụ với `@mcp.tool`
  - Các ví dụ hoạt động hoàn chỉnh
  - Danh sách kiểm tra chất lượng

- [⚡ Hướng Dẫn Triển Khai TypeScript](./reference/node_mcp_server.md) - Hướng dẫn toàn diện về TypeScript bao gồm:
  - Cấu trúc dự án
  - Các mẫu lược đồ Zod
  - Đăng ký công cụ với `server.registerTool`
  - Các ví dụ hoạt động hoàn chỉnh
  - Danh sách kiểm tra chất lượng

### Hướng Dẫn Đánh Giá (Tải Trong Giai Đoạn 4)
- [✅ Hướng Dẫn Đánh Giá](./reference/evaluation.md) - Hướng dẫn toàn diện về cách tạo bộ đánh giá bao gồm:
  - Nguyên tắc đặt câu hỏi đánh giá
  - Chiến lược xác minh đáp án
  - Đặc tả định dạng XML
  - Ví dụ câu hỏi và câu trả lời mẫu
  - Cách chạy đánh giá bằng các kịch bản lệnh (scripts) được cung cấp
FILE:reference/mcp_best_practices.md
# Thực Hành Tốt Nhất Cho Máy Chủ MCP (MCP Server Best Practices)

## Tham Khảo Nhanh

### Đặt Tên Máy Chủ
- **Python**: `{service}_mcp` (ví dụ: `slack_mcp`)
- **Node/TypeScript**: `{service}-mcp-server` (ví dụ: `slack-mcp-server`)

### Đặt Tên Công Cụ
- Sử dụng kiểu chữ snake_case có kèm tiền tố tên dịch vụ
- Định dạng: `{service}_{action}_{resource}`
- Ví dụ: `slack_send_message`, `github_create_issue`

### Định Dạng Phản Hồi
- Hỗ trợ cả hai định dạng JSON và Markdown
- JSON phục vụ việc xử lý bằng mã chương trình
- Markdown giúp con người dễ đọc trực tiếp

### Phân Trang (Pagination)
- Luôn tôn trọng tham số giới hạn `limit`
- Trả về đầy đủ `has_more`, `next_offset`, `total_count`
- Giá trị mặc định từ 20-50 mục

### Phương Thức Truyền Tải (Transport)
- **Streamable HTTP**: Dành cho máy chủ từ xa, kịch bản phục vụ nhiều trình khách cùng lúc
- **stdio**: Dành cho tích hợp cục bộ, các công cụ dòng lệnh
- Tránh dùng SSE (đã ngừng khuyến khích sử dụng để chuyển sang streamable HTTP)

---

## Quy Ước Đặt Tên Máy Chủ

Tuân thủ các mẫu đặt tên tiêu chuẩn hóa sau đây:

**Python**: Sử dụng định dạng `{service}_mcp` (chữ thường nối bằng dấu gạch dưới)
- Ví dụ: `slack_mcp`, `github_mcp`, `jira_mcp`

**Node/TypeScript**: Sử dụng định dạng `{service}-mcp-server` (chữ thường nối bằng dấu gạch ngang)
- Ví dụ: `slack-mcp-server`, `github-mcp-server`, `jira-mcp-server`

Tên máy chủ cần mang tính khái quát, mô tả rõ dịch vụ đang được tích hợp, dễ dàng suy luận ra từ mô tả tác vụ, và không kèm theo số phiên bản.

---

## Đặt Tên và Thiết Kế Công Cụ

### Đặt Tên Công Cụ

1. **Sử dụng snake_case**: `search_users`, `create_project`, `get_channel_info`
2. **Bao gồm tiền tố tên dịch vụ**: Hãy lường trước việc máy chủ MCP của bạn có thể được sử dụng chung cùng lúc với nhiều máy chủ MCP khác
   - Sử dụng `slack_send_message` thay vì chỉ viết `send_message`
   - Sử dụng `github_create_issue` thay vì chỉ viết `create_issue`
3. **Hướng tới hành động**: Bắt đầu bằng các động từ (get, list, search, create, v.v.)
4. **Cụ thể và rõ ràng**: Tránh những cái tên chung chung dễ gây xung đột với các máy chủ khác

### Thiết Kế Công Cụ

- Phần mô tả công cụ phải diễn tả chính xác, thu hẹp và không gây nhập nhằng về chức năng
- Nội dung mô tả phải khớp tuyệt đối với chức năng thực tế mà công cụ thực hiện
- Cung cấp đầy đủ các chú giải công cụ (readOnlyHint, destructiveHint, idempotentHint, openWorldHint)
- Giữ cho các thao tác của công cụ tập trung và mang tính nguyên tử (atomic)

---

## Định Dạng Phản Hồi (Response Formats)

Tất cả các công cụ trả về dữ liệu nên hỗ trợ nhiều định dạng đầu ra:

### Định Dạng JSON (`response_format="json"`)
- Dữ liệu có cấu trúc để máy tính đọc và xử lý (machine-readable)
- Bao gồm tất cả các trường dữ liệu và siêu dữ liệu (metadata) hiện có
- Tên trường và kiểu dữ liệu nhất quán
- Sử dụng cho việc xử lý tự động bằng chương trình

### Định Dạng Markdown (`response_format="markdown"`, thường là mặc định)
- Văn bản đã được định dạng để con người dễ đọc
- Sử dụng tiêu đề, danh sách và định dạng chữ để trình bày rõ ràng
- Chuyển đổi dấu thời gian (timestamps) sang định dạng ngày giờ dễ đọc
- Hiển thị tên hiển thị kèm theo mã ID đặt trong dấu ngoặc đơn
- Lược bỏ các siêu dữ liệu rườm rà không cần thiết

---

## Phân Trang (Pagination)

Đối với các công cụ liệt kê danh sách tài nguyên:

- **Luôn tôn trọng tham số `limit`**
- **Triển khai phân trang**: Sử dụng phân trang theo vị trí `offset` hoặc theo con trỏ `cursor`
- **Trả về siêu dữ liệu phân trang**: Bao gồm `has_more`, `next_offset`/`next_cursor`, `total_count`
- **Không bao giờ nạp toàn bộ kết quả vào bộ nhớ**: Đặc biệt quan trọng đối với các tập dữ liệu lớn
- **Đặt giới hạn mặc định hợp lý**: Thông thường từ 20-50 mục mỗi trang

Ví dụ phản hồi có phân trang:
```json
{
  "total": 150,
  "count": 20,
  "offset": 0,
  "items": [...],
  "has_more": true,
  "next_offset": 20
}
```

---

## Các Tùy Chọn Truyền Tải (Transport Options)

### Streamable HTTP

**Tốt nhất cho**: Máy chủ từ xa, dịch vụ web, kịch bản có nhiều trình khách (multi-client)

**Đặc điểm**:
- Giao tiếp hai chiều qua giao thức HTTP
- Hỗ trợ nhiều trình khách kết nối đồng thời
- Có thể triển khai như một dịch vụ web độc lập
- Cho phép gửi thông báo từ máy chủ tới trình khách (server-to-client notifications)

**Sử dụng khi**:
- Phục vụ nhiều trình khách cùng một lúc
- Triển khai dưới dạng dịch vụ đám mây
- Tích hợp với các ứng dụng nền web

### stdio

**Tốt nhất cho**: Tích hợp cục bộ trên máy, các công cụ dòng lệnh (CLI)

**Đặc điểm**:
- Giao tiếp qua luồng đầu vào/đầu ra tiêu chuẩn (standard input/output stream)
- Thiết lập đơn giản, không cần cấu hình mạng
- Chạy như một tiến trình con (subprocess) của trình khách

**Sử dụng khi**:
- Xây dựng công cụ cho môi trường phát triển cục bộ
- Tích hợp với các ứng dụng máy tính để bàn (desktop apps)
- Kịch bản một người dùng, một phiên làm việc duy nhất

**Lưu ý**: Các máy chủ stdio TUYỆT ĐỐI KHÔNG được ghi nhật ký (log) ra luồng stdout (hãy sử dụng luồng stderr để ghi log)

### Lựa Chọn Phương Thức Truyền Tải

| Tiêu chí | stdio | Streamable HTTP |
|-----------|-------|-----------------|
| **Triển khai** | Cục bộ (Local) | Từ xa (Remote) |
| **Số trình khách** | Đơn lẻ (Single) | Đa trình khách (Multiple) |
| **Độ phức tạp** | Thấp | Trung bình |
| **Thời gian thực** | Không | Có |

---

## Thực Hành Tốt Nhất Về Bảo Mật

### Xác Thực và Phân Quyền

**OAuth 2.1**:
- Sử dụng chuẩn OAuth 2.1 bảo mật với chứng chỉ từ các tổ chức cấp phát được công nhận
- Xác thực mã thông báo truy cập (access tokens) trước khi xử lý bất kỳ yêu cầu nào
- Chỉ chấp nhận các token được cấp riêng cho đúng máy chủ của bạn

**Khóa API (API Keys)**:
- Lưu trữ khóa API trong các biến môi trường, không bao giờ gán cứng trong mã nguồn
- Kiểm tra tính hợp lệ của khóa ngay khi khởi động máy chủ
- Đưa ra thông báo lỗi rõ ràng khi quá trình xác thực thất bại

### Xác Thực Dữ Liệu Đầu Vào (Input Validation)

- Làm sạch đường dẫn tệp để ngăn chặn tấn công duyệt thư mục (directory traversal)
- Kiểm tra tính hợp lệ của các URL và mã định danh bên ngoài
- Kiểm tra kích thước và miền giá trị của các tham số
- Ngăn chặn lỗ hổng tiêm lệnh (command injection) trong các lệnh gọi hệ thống
- Sử dụng xác thực lược đồ (Pydantic/Zod) cho tất cả dữ liệu đầu vào

### Xử Lý Lỗi (Error Handling)

- Không làm lộ chi tiết lỗi nội bộ của hệ thống ra phía trình khách
- Ghi nhật ký các lỗi liên quan đến bảo mật ở phía máy chủ
- Cung cấp thông báo lỗi hữu ích nhưng không tiết lộ thông tin nhạy cảm
- Dọn dẹp giải phóng tài nguyên sau khi xảy ra lỗi

### Bảo Vệ Chống Tấn Công DNS Rebinding

Đối với các máy chủ streamable HTTP chạy cục bộ:
- Bật cơ chế bảo vệ chống DNS rebinding
- Kiểm tra xác thực tiêu đề `Origin` trên tất cả các kết nối gửi đến
- Lắng nghe kết nối trên địa chỉ `127.0.0.1` thay vì `0.0.0.0`

---

## Chú Giải Công Cụ (Tool Annotations)

Cung cấp các chú giải để giúp trình khách hiểu rõ hành vi của công cụ:

| Chú giải (Annotation) | Kiểu | Mặc định | Mô tả |
|-----------|------|---------|-------------|
| `readOnlyHint` | boolean | false | Công cụ không làm thay đổi môi trường của nó |
| `destructiveHint` | boolean | true | Công cụ có thể thực hiện các cập nhật mang tính xóa/phá hủy |
| `idempotentHint` | boolean | false | Gọi lặp lại nhiều lần với cùng đối số không gây thêm tác động phụ |
| `openWorldHint` | boolean | true | Công cụ tương tác với các thực thể bên ngoài |

**Quan trọng**: Các chú giải chỉ mang tính chất gợi ý (hints), không phải là cam kết bảo đảm an ninh. Trình khách không nên đưa ra các quyết định bảo mật trọng yếu chỉ dựa đơn thuần vào các chú giải này.

---

## Xử Lý Lỗi Trong Giao Thức

- Sử dụng các mã lỗi JSON-RPC tiêu chuẩn
- Báo cáo lỗi thực thi công cụ ngay bên trong đối tượng kết quả trả về (thay vì ném lỗi ở cấp độ giao thức)
- Cung cấp thông báo lỗi cụ thể, hữu ích kèm theo gợi ý các bước tiếp theo nên làm
- Không phơi bày chi tiết cài đặt nội bộ
- Dọn dẹp tài nguyên đúng cách khi xảy ra lỗi

Ví dụ về xử lý lỗi:
```typescript
try {
  const result = performOperation();
  return { content: [{ type: "text", text: result }] };
} catch (error) {
  return {
    isError: true,
    content: [{
      type: "text",
      text: `Error: error.message. Try using filter='active_only' to reduce results.`
    }]
  };
}
```

---

## Yêu Cầu Về Kiểm Thử (Testing Requirements)

Hoạt động kiểm thử toàn diện cần bao quát các mảng sau:

- **Kiểm thử chức năng (Functional testing)**: Xác minh công cụ thực thi chính xác với cả dữ liệu đầu vào hợp lệ lẫn không hợp lệ
- **Kiểm thử tích hợp (Integration testing)**: Kiểm thử sự tương tác thực tế với các hệ thống bên ngoài
- **Kiểm thử bảo mật (Security testing)**: Xác thực cơ chế đăng nhập/ủy quyền, làm sạch dữ liệu đầu vào, giới hạn tần suất gọi (rate limiting)
- **Kiểm thử hiệu năng (Performance testing)**: Kiểm tra hành vi của hệ thống dưới tải cao và khi xảy ra hết thời gian chờ (timeouts)
- **Xử lý lỗi (Error handling)**: Đảm bảo việc báo cáo lỗi và dọn dẹp tài nguyên diễn ra đúng chuẩn

---

## Yêu Cầu Về Tài Liệu (Documentation Requirements)

- Cung cấp tài liệu hướng dẫn rõ ràng cho tất cả các công cụ và năng lực của máy chủ
- Bao gồm các ví dụ hoạt động thực tế (ít nhất 3 ví dụ cho mỗi tính năng chính)
- Ghi rõ các lưu ý về an toàn bảo mật
- Chỉ rõ các quyền hạn (permissions) và cấp độ truy cập bắt buộc phải có
- Ghi rõ giới hạn tần suất gọi (rate limits) và các đặc tính hiệu năng
FILE:reference/evaluation.md
# Hướng Dẫn Đánh Giá Máy Chủ MCP (MCP Server Evaluation Guide)

## Tổng Quan

Tài liệu này cung cấp hướng dẫn xây dựng các bộ đánh giá toàn diện cho các máy chủ MCP. Các bài đánh giá này kiểm tra xem liệu các mô hình ngôn ngữ lớn (LLM) có thể sử dụng hiệu quả máy chủ MCP của bạn để trả lời những câu hỏi thực tế, phức tạp khi chỉ được phép dùng các công cụ do máy chủ cung cấp hay không.

---

## Tham Khảo Nhanh

### Yêu Cầu Đánh Giá
- Tạo 10 câu hỏi dễ đọc đối với con người
- Các câu hỏi phải CHỈ ĐỌC (READ-ONLY), ĐỘC LẬP (INDEPENDENT), KHÔNG PHÁ HỦY DỮ LIỆU (NON-DESTRUCTIVE)
- Mỗi câu hỏi đòi hỏi phải gọi nhiều lệnh công cụ (có thể lên tới hàng chục lần gọi)
- Đáp án phải là một giá trị đơn lẻ, có thể kiểm chứng được
- Đáp án phải ỔN ĐỊNH (STABLE — không bị thay đổi theo thời gian)

### Định Dạng Đầu Ra
```xml
<evaluation>
   <qa_pair>
      <question>Your question here</question>
      <answer>Single verifiable answer</answer>
   </qa_pair>
</evaluation>
```

---

## Mục Đích Của Việc Đánh Giá

Thước đo chất lượng của một máy chủ MCP KHÔNG nằm ở việc máy chủ đó cài đặt công cụ nhiều hay khéo léo ra sao trên lý thuyết, mà nằm ở mức độ hiệu quả mà các cài đặt đó (lược đồ đầu vào/đầu ra, chuỗi tài liệu docstrings/mô tả, tính năng thực tế) giúp cho các LLM—vốn không có thêm bất kỳ ngữ cảnh nào khác và CHỈ được quyền truy cập vào máy chủ MCP đó—trả lời được những câu hỏi thực tế và hóc búa.

## Tổng Quan Về Bộ Đánh Giá

Hãy tạo 10 câu hỏi dễ đọc đối với con người, chỉ yêu cầu các thao tác CHỈ ĐỌC (READ-ONLY), ĐỘC LẬP (INDEPENDENT), KHÔNG PHÁ HỦY (NON-DESTRUCTIVE) và LŨY ĐẲNG (IDEMPOTENT) để tìm ra câu trả lời. Mỗi câu hỏi cần phải:
- Sát với thực tế (Realistic)
- Rõ ràng và ngắn gọn súc tích (Clear and concise)
- Không nhập nhằng đa nghĩa (Unambiguous)
- Phức tạp, đòi hỏi có thể lên tới hàng chục lần gọi công cụ hoặc nhiều bước suy luận nối tiếp
- Có thể trả lời bằng một giá trị đơn lẻ, kiểm chứng được mà bạn đã xác định trước đáp án

## Nguyên Tắc Đặt Câu Hỏi

### Các Yêu Cầu Cốt Lõi

1. **Các câu hỏi BẮT BUỘC phải độc lập với nhau**
   - Mỗi câu hỏi KHÔNG ĐƯỢC phụ thuộc vào đáp án của bất kỳ câu hỏi nào khác
   - Không được giả định rằng đã có các thao tác ghi dữ liệu trước đó từ quá trình xử lý câu hỏi khác

2. **Các câu hỏi BẮT BUỘC chỉ yêu cầu sử dụng công cụ KHÔNG PHÁ HỦY VÀ LŨY ĐẲNG**
   - Không được chỉ dẫn hoặc yêu cầu phải sửa đổi trạng thái dữ liệu mới tìm ra được đáp án đúng

3. **Các câu hỏi phải THỰC TẾ, RÕ RÀNG, NGẮN GỌN và PHỨC TẠP**
   - Phải buộc một LLM khác phải sử dụng nhiều (có thể là hàng chục) công cụ hoặc bước xử lý mới trả lời được

### Độ Phức Tạp và Chiều Sâu

4. **Các câu hỏi phải đòi hỏi sự khám phá sâu (deep exploration)**
   - Hãy cân nhắc các câu hỏi đa chặng (multi-hop questions) đòi hỏi phải giải quyết nhiều câu hỏi phụ và gọi công cụ tuần tự nối tiếp nhau
   - Mỗi bước sau sẽ tận dụng thông tin vừa tìm thấy ở bước truy vấn trước đó

5. **Các câu hỏi có thể đòi hỏi phải lật trang dữ liệu nhiều lần (extensive paging)**
   - Có thể cần phải duyệt qua nhiều trang kết quả trả về
   - Có thể đòi hỏi phải truy vấn dữ liệu cũ (cách đây 1-2 năm) để tìm ra thông tin ngách
   - Các câu hỏi bắt buộc phải KHÓ (DIFFICULT)

6. **Các câu hỏi phải đòi hỏi sự hiểu biết sâu sắc**
   - Chứ không chỉ là kiến thức bề nổi
   - Có thể đặt ra các ý niệm phức tạp dưới dạng câu hỏi Đúng/Sai (True/False) đòi hỏi phải tìm bằng chứng xác thực
   - Có thể sử dụng định dạng trắc nghiệm nhiều lựa chọn buộc LLM phải tìm kiếm kiểm chứng nhiều giả thuyết khác nhau

7. **Các câu hỏi không thể giải quyết chỉ bằng một lệnh tìm kiếm từ khóa đơn giản**
   - Không đưa nguyên xi các từ khóa đặc thù có sẵn trong nội dung mục tiêu vào câu hỏi
   - Hãy sử dụng từ đồng nghĩa, các khái niệm liên quan hoặc diễn đạt lại bằng lời văn khác (paraphrases)
   - Đòi hỏi phải tìm kiếm nhiều lần, phân tích nhiều mục liên quan, trích xuất ngữ cảnh rồi mới suy ra được câu trả lời

### Kiểm Thử Sức Chịu Tải Của Công Cụ (Tool Testing)

8. **Các câu hỏi nên kiểm thử áp lực (stress-test) đối với giá trị trả về của công cụ**
   - Có thể kích hoạt các công cụ trả về những đối tượng JSON hoặc danh sách lớn dễ làm quá tải ngữ cảnh của LLM
   - Cần đòi hỏi khả năng hiểu nhiều dạng thức dữ liệu (modalities) khác nhau:
     - Mã định danh (ID) và tên gọi
     - Dấu thời gian (timestamps) và ngày giờ (tháng, ngày, năm, giây)
     - Mã ID tệp tin, tên tệp, phần mở rộng và kiểu MIME (mimetypes)
     - Các đường dẫn URL, mã GID, v.v.
   - Cần thăm dò khả năng của công cụ trong việc trả về mọi dạng dữ liệu hữu ích

9. **Các câu hỏi PHẦN LỚN phải phản ánh đúng các trường hợp sử dụng thực tế của con người**
   - Những tác vụ truy xuất thông tin mà CON NGƯỜI khi nhờ LLM hỗ trợ sẽ thực sự quan tâm

10. **Các câu hỏi có thể đòi hỏi hàng chục lần gọi công cụ**
    - Điều này tạo ra thử thách thực sự cho các LLM có cửa sổ ngữ cảnh giới hạn
    - Khuyến khích các công cụ trên máy chủ MCP được thiết kế gọn lại để giảm lượng thông tin thừa trả về

11. **Đưa vào cả các câu hỏi có tính mơ hồ cần suy luận**
    - Có thể hơi mơ hồ HOẶC đòi hỏi phải đưa ra quyết định khó khăn xem nên gọi công cụ nào
    - Buộc LLM có khả năng mắc sai lầm hoặc hiểu sai nếu không suy xét kỹ
    - Tuy nhiên, phải đảm bảo rằng bất chấp SỰ MƠ HỒ ban đầu, VẪN LUÔN CÓ MỘT ĐÁP ÁN DUY NHẤT CÓ THỂ KIỂM CHỨNG ĐƯỢC

### Tính Ổn Định (Stability)

12. **Các câu hỏi phải được thiết kế sao cho ĐÁP ÁN KHÔNG BỊ THAY ĐỔI THEO THỜI GIAN**
    - Không đặt những câu hỏi phụ thuộc vào "trạng thái hiện tại" vốn luôn biến động
    - Ví dụ, không đếm:
      - Số lượng biểu cảm (reactions) trên một bài đăng
      - Số lượng phản hồi trong một chuỗi tin nhắn (thread)
      - Số lượng thành viên trong một kênh trò chuyện

13. **ĐỪNG để máy chủ MCP GIỚI HẠN các loại câu hỏi mà bạn tạo ra**
    - Hãy tạo ra những câu hỏi đầy thử thách và phức tạp
    - Một số câu hỏi có thể không giải quyết được ngay nếu bộ công cụ hiện tại của máy chủ MCP còn thiếu sót
    - Các câu hỏi có thể yêu cầu định dạng đầu ra cụ thể (ngày giờ chuẩn datetime so với thời gian epoch, JSON so với MARKDOWN)
    - Các câu hỏi có thể đòi hỏi hàng chục lần gọi công cụ mới hoàn thành

## Nguyên Tắc Về Đáp Án (Answer Guidelines)

### Khả Năng Kiểm Chứng (Verification)

1. **Đáp án bắt buộc phải KIỂM CHỨNG ĐƯỢC thông qua phép so sánh chuỗi trực tiếp (direct string comparison)**
   - Nếu câu trả lời có thể được viết theo nhiều định dạng khác nhau, hãy chỉ định rõ định dạng đầu ra bắt buộc ngay trong CÂU HỎI
   - Ví dụ: "Sử dụng định dạng YYYY/MM/DD.", "Chỉ trả lời True hoặc False.", "Chỉ trả lời A, B, C, hoặc D và không viết thêm bất kỳ chữ nào khác."
   - Đáp án phải là một giá trị ĐƠN LẺ, KIỂM CHỨNG ĐƯỢC chẳng hạn như:
     - Mã ID người dùng, tên đăng nhập, tên hiển thị, tên riêng, họ
     - Mã ID kênh, tên kênh
     - Mã ID tin nhắn, chuỗi văn bản
     - Đường dẫn URL, tiêu đề
     - Số lượng bằng con số cụ thể
     - Dấu thời gian (timestamp), ngày giờ (datetime)
     - Giá trị logic Boolean (đối với câu hỏi True/False)
     - Địa chỉ email, số điện thoại
     - Mã ID tệp, tên tệp, phần mở rộng tệp
     - Đáp án trắc nghiệm (A/B/C/D)
   - Đáp án không được đòi hỏi định dạng đặc biệt hoặc cấu trúc đầu ra phức tạp
   - Đáp án sẽ được chấm tự động bằng PHÉP SO SÁNH CHUỖI TRỰC TIẾP

### Tính Dễ Đọc (Readability)

2. **Đáp án nhìn chung nên ưu tiên các định dạng CON NGƯỜI DỄ ĐỌC (HUMAN-READABLE)**
   - Ví dụ: tên gọi, tên riêng, họ, ngày giờ, tên tệp, chuỗi tin nhắn, URL, yes/no, true/false, a/b/c/d
   - Thay vì những mã ID tối nghĩa (mặc dù mã ID vẫn được chấp nhận khi cần thiết)
   - ĐẠI ĐA SỐ các đáp án nên ở dạng con người đọc hiểu được ngay

### Tính Ổn Định (Stability)

3. **Đáp án bắt buộc phải ỔN ĐỊNH / TĨNH (STABLE/STATIONARY)**
   - Hãy khai thác các nội dung cũ trong lịch sử (ví dụ: các cuộc trò chuyện đã kết thúc, các dự án đã ra mắt xong, các câu hỏi đã được giải đáp hoàn tất)
   - Tạo CÂU HỎI dựa trên các sự kiện/khái niệm "đã đóng lại" để luôn trả về cùng một kết quả bất biến
   - Câu hỏi có thể yêu cầu xét trong một khung thời gian cố định trong quá khứ để cách ly khỏi những biến động mới
   - Dựa vào ngữ cảnh RẤT ÍT KHẢ NĂNG bị thay đổi
   - Ví dụ: nếu yêu cầu tìm tên một bài báo khoa học, hãy đặt điều kiện ĐỦ CỤ THỂ để đáp án không bị nhầm lẫn với các bài báo mới xuất bản sau này

4. **Đáp án phải RÕ RÀNG và KHÔNG ĐA NGHĨA**
   - Câu hỏi phải được thiết kế sao cho chỉ dẫn tới một đáp án rõ ràng duy nhất
   - Đáp án có thể suy ra được bằng cách sử dụng các công cụ của máy chủ MCP

### Tính Đa Dạng (Diversity)

5. **Các đáp án phải ĐA DẠNG**
   - Đáp án trong bộ câu hỏi nên là các giá trị đơn lẻ thuộc nhiều dạng thức và khía cạnh khác nhau
   - Khái niệm người dùng: mã ID người dùng, tên đăng nhập, tên hiển thị, tên riêng, họ, địa chỉ email, số điện thoại
   - Khái niệm kênh: mã ID kênh, tên kênh, chủ đề kênh (channel topic)
   - Khái niệm tin nhắn: mã ID tin nhắn, nội dung chuỗi tin nhắn, dấu thời gian, tháng, ngày, năm

6. **Đáp án KHÔNG ĐƯỢC là các cấu trúc phức tạp**
   - Không phải là một danh sách gồm nhiều giá trị
   - Không phải là một đối tượng dữ liệu phức tạp
   - Không phải là một danh sách các mã ID hoặc chuỗi ký tự
   - Không phải là một đoạn văn bản ngôn ngữ tự nhiên tự do
   - TRỪ KHI đáp án đó có thể dễ dàng kiểm chứng bằng PHÉP SO SÁNH CHUỖI TRỰC TIẾP
   - Và có thể tái tạo lại một cách nhất quán trong thực tế
   - Phải đảm bảo rất khó xảy ra khả năng một LLM trả về cùng danh sách đó nhưng theo một thứ tự hay định dạng khác

## Quy Trình Xây Dựng Bộ Đánh Giá (Evaluation Process)

### Bước 1: Khảo Sát Tài Liệu (Documentation Inspection)

Đọc tài liệu của API mục tiêu để nắm rõ:
- Các điểm cuối (endpoints) và chức năng hiện có
- Nếu có điểm nào chưa rõ ràng, hãy truy xuất thêm thông tin từ trên web
- Thực hiện song song hóa bước này NHIỀU NHẤT CÓ THỂ
- Đảm bảo mỗi tác tử con (subagent) CHỈ xem xét tài liệu từ hệ thống tệp hoặc trên web

### Bước 2: Khảo Sát Công Cụ (Tool Inspection)

Liệt kê các công cụ hiện có trong máy chủ MCP:
- Kiểm tra trực tiếp máy chủ MCP
- Tìm hiểu lược đồ đầu vào/đầu ra, chuỗi tài liệu docstrings và phần mô tả
- MÀ KHÔNG thực sự gọi thực thi các công cụ đó ở giai đoạn này

### Bước 3: Xây Dựng Sự Hiểu Biết Tổng Thể

Lặp lại bước 1 & 2 cho đến khi bạn nắm vững cơ chế hoạt động:
- Lặp lại nhiều vòng
- Suy nghĩ về các loại tác vụ thực tế mà bạn muốn tạo ra
- Tinh chỉnh lại sự hiểu biết của mình
- Ở BẤT KỲ giai đoạn nào, bạn cũng TUYỆT ĐỐI KHÔNG ĐƯỢC ĐỌC mã nguồn cài đặt bên trong của chính máy chủ MCP
- Hãy dùng trực giác và sự hiểu biết của bạn về miền nghiệp vụ để tạo ra những tác vụ hợp lý, thực tế nhưng CỰC KỲ thử thách

### Bước 4: Khảo Sát Nội Dung Ở Chế Độ Chỉ Đọc (Read-Only Content Inspection)

Sau khi đã hiểu rõ API và các công cụ, hãy SỬ DỤNG các công cụ của máy chủ MCP:
- Khảo sát nội dung dữ liệu CHỈ bằng các thao tác CHỈ ĐỌC (READ-ONLY) và KHÔNG PHÁ HỦY (NON-DESTRUCTIVE)
- Mục tiêu: xác định các nội dung cụ thể có thực (ví dụ: người dùng, kênh, tin nhắn, dự án, công việc) để làm chất liệu tạo câu hỏi thực tế
- TUYỆT ĐỐI KHÔNG gọi bất kỳ công cụ nào làm sửa đổi trạng thái dữ liệu
- TUYỆT ĐỐI KHÔNG đọc mã nguồn cài đặt của chính máy chủ MCP
- Song song hóa bước này với các tác tử con độc lập tiến hành khám phá các nhánh dữ liệu khác nhau
- Đảm bảo mỗi tác tử con chỉ thực hiện các thao tác CHỈ ĐỌC, KHÔNG PHÁ HỦY và LŨY ĐẲNG
- HÃY CẨN THẬN: MỘT SỐ CÔNG CỤ có thể trả về LƯỢNG DỮ LIỆU RẤT LỚN làm tràn bộ nhớ NGỮ CẢNH (CONTEXT) của bạn
- Hãy thực hiện các lệnh gọi công cụ NHỎ, TĂNG DẦN TỪNG BƯỚC VÀ CÓ TRỌNG TÂM để khám phá
- Trong tất cả các yêu cầu gọi công cụ, hãy luôn sử dụng tham số `limit` để giới hạn số lượng kết quả trả về (<10)
- Sử dụng tính năng phân trang (pagination)

### Bước 5: Tạo Bộ Câu Hỏi Đánh Giá (Task Generation)

Sau khi đã khảo sát xong nội dung thực tế, hãy tạo ra 10 câu hỏi dễ đọc đối với con người:
- Một LLM phải có khả năng trả lời được những câu hỏi này thông qua máy chủ MCP
- Tuân thủ đầy đủ mọi nguyên tắc về câu hỏi và đáp án đã nêu ở trên

## Định Dạng Đầu Ra

Mỗi cặp Hỏi-Đáp (QA pair) bao gồm một câu hỏi và một đáp án. Đầu ra phải là một tệp XML có cấu trúc như sau:

```xml
<evaluation>
   <qa_pair>
      <question>Find the project created in Q2 2024 with the highest number of completed tasks. What is the project name?</question>
      <answer>Website Redesign</answer>
   </qa_pair>
   <qa_pair>
      <question>Search for issues labeled as "bug" that were closed in March 2024. Which user closed the most issues? Provide their username.</question>
      <answer>sarah_dev</answer>
   </qa_pair>
   <qa_pair>
      <question>Look for pull requests that modified files in the /api directory and were merged between January 1 and January 31, 2024. How many different contributors worked on these PRs?</question>
      <answer>7</answer>
   </qa_pair>
   <qa_pair>
      <question>Find the repository with the most stars that was created before 2023. What is the repository name?</question>
      <answer>data-pipeline</answer>
   </qa_pair>
</evaluation>
```

## Các Ví Dụ Về Câu Hỏi Đánh Giá

### Những Câu Hỏi Tốt (Good Questions)

**Ví dụ 1: Câu hỏi đa chặng đòi hỏi khám phá sâu (GitHub MCP)**
```xml
<qa_pair>
   <question>Find the repository that was archived in Q3 2023 and had previously been the most forked project in the organization. What was the primary programming language used in that repository?</question>
   <answer>Python</answer>
</qa_pair>
```

Câu hỏi này tốt vì:
- Đòi hỏi nhiều lần tìm kiếm để lọc ra các kho lưu trữ đã đưa vào lưu trữ (archived repositories)
- Cần xác định xem kho nào có nhiều lượt rẽ nhánh (forks) nhất trước khi bị lưu trữ
- Đòi hỏi phải kiểm tra chi tiết từng kho lưu trữ để biết ngôn ngữ lập trình chính
- Đáp án là một giá trị đơn giản, dễ kiểm chứng
- Dựa trên dữ liệu lịch sử (đã đóng lại) nên sẽ không thay đổi theo thời gian

**Ví dụ 2: Đòi hỏi hiểu ngữ cảnh mà không khớp từ khóa trực tiếp (Project Management MCP)**
```xml
<qa_pair>
   <question>Locate the initiative focused on improving customer onboarding that was completed in late 2023. The project lead created a retrospective document after completion. What was the lead's role title at that time?</question>
   <answer>Product Manager</answer>
</qa_pair>
```

Câu hỏi này tốt vì:
- Không nêu thẳng tên dự án cụ thể (mà mô tả là "sáng kiến tập trung vào việc cải thiện quy trình đón tiếp khách hàng mới")
- Đòi hỏi phải tìm các dự án đã hoàn thành trong một khung thời gian cụ thể
- Cần xác định người phụ trách dự án (project lead) và vai trò của họ
- Đòi hỏi phải đọc hiểu ngữ cảnh từ các tài liệu họp rút kinh nghiệm (retrospective documents)
- Đáp án dễ đọc đối với con người và giữ nguyên tính ổn định
- Dựa trên công việc đã hoàn tất trong quá khứ (sẽ không biến đổi)

**Ví dụ 3: Tổng hợp phức tạp đòi hỏi nhiều bước xử lý (Issue Tracker MCP)**
```xml
<qa_pair>
   <question>Among all bugs reported in January 2024 that were marked as critical priority, which assignee resolved the highest percentage of their assigned bugs within 48 hours? Provide the assignee's username.</question>
   <answer>alex_eng</answer>
</qa_pair>
```

Câu hỏi này tốt vì:
- Đòi hỏi phải lọc các lỗi (bugs) theo ngày tháng, mức độ ưu tiên và trạng thái
- Cần gom nhóm theo người được giao việc (assignee) và tính toán tỷ lệ giải quyết thành công
- Đòi hỏi phải xử lý dấu thời gian (timestamps) để xác định đúng khoảng thời gian 48 giờ
- Kiểm thử khả năng phân trang (có khả năng phải duyệt qua rất nhiều lỗi)
- Đáp án là một tên người dùng (username) duy nhất
- Dựa trên dữ liệu lịch sử trong một giai đoạn thời gian cố định

**Ví dụ 4: Đòi hỏi tổng hợp thông tin xuyên qua nhiều loại dữ liệu (CRM MCP)**
```xml
<qa_pair>
   <question>Find the account that upgraded from the Starter to Enterprise plan in Q4 2023 and had the highest annual contract value. What industry does this account operate in?</question>
   <answer>Healthcare</answer>
</qa_pair>
```

Câu hỏi này tốt vì:
- Đòi hỏi phải nắm được lịch sử thay đổi gói thuê bao (subscription tier changes)
- Cần xác định các sự kiện nâng cấp gói trong một khung thời gian cụ thể
- Đòi hỏi phải so sánh giá trị hợp đồng
- Phải truy cập thông tin ngành nghề kinh doanh của tài khoản khách hàng
- Đáp án đơn giản và có thể kiểm chứng rõ ràng
- Dựa trên các giao dịch lịch sử đã hoàn tất

### Những Câu Hỏi Kém Chất Lượng (Poor Questions)

**Ví dụ 1: Đáp án thay đổi theo thời gian**
```xml
<qa_pair>
   <question>How many open issues are currently assigned to the engineering team?</question>
   <answer>47</answer>
</qa_pair>
```

Câu hỏi này kém vì:
- Đáp án sẽ liên tục thay đổi khi có thêm các issue mới được tạo ra, đóng lại hoặc chuyển giao cho người khác
- Không dựa trên dữ liệu tĩnh/ổn định
- Phụ thuộc vào "trạng thái hiện tại" vốn luôn biến động

**Ví dụ 2: Quá dễ khi chỉ cần tìm kiếm từ khóa**
```xml
<qa_pair>
   <question>Find the pull request with title "Add authentication feature" and tell me who created it.</question>
   <answer>developer123</answer>
</qa_pair>
```

Câu hỏi này kém vì:
- Có thể giải quyết ngay bằng một lệnh tìm kiếm từ khóa đơn giản theo đúng tiêu đề chính xác
- Không đòi hỏi phải khám phá sâu hay đọc hiểu ngữ cảnh
- Không cần tổng hợp hay phân tích dữ liệu

**Ví dụ 3: Định dạng đáp án mơ hồ**
```xml
<qa_pair>
   <question>List all the repositories that have Python as their primary language.</question>
   <answer>repo1, repo2, repo3, data-pipeline, ml-tools</answer>
</qa_pair>
```

Câu hỏi này kém vì:
- Đáp án là một danh sách có thể được trả về theo bất kỳ thứ tự nào
- Rất khó kiểm chứng tự động bằng phép so sánh chuỗi trực tiếp
- LLM có thể trình bày theo nhiều kiểu khác nhau (mảng JSON, phân cách bằng dấu phẩy, xuống dòng)
- Tốt hơn hết nên hỏi một con số tổng hợp cụ thể (đếm số lượng) hoặc giá trị cực đại (nhiều sao nhất)

## Quy Trình Xác Minh Đáp Án (Verification Process)

Sau khi tạo xong bộ câu hỏi đánh giá:

1. **Kiểm tra tệp XML** để nắm rõ cấu trúc lược đồ
2. **Tải từng chỉ dẫn câu hỏi** và sử dụng máy chủ MCP cùng các công cụ theo hướng chạy song song để TỰ MÌNH giải bài toán nhằm xác định đáp án chính xác thực tế
3. **Đánh dấu bất kỳ thao tác nào** đòi hỏi quyền GHI (WRITE) hoặc PHÁ HỦY (DESTRUCTIVE) dữ liệu
4. **Tập hợp tất cả các đáp án ĐÚNG** và thay thế bất kỳ đáp án sai lệch nào trong tài liệu
5. **Loại bỏ bất kỳ cặp `<qa_pair>` nào** đòi hỏi thao tác GHI hoặc PHÁ HỦY dữ liệu

Hãy nhớ chạy song song quá trình giải các câu hỏi để tránh làm tràn bộ nhớ ngữ cảnh, sau đó gom tất cả các đáp án lại và cập nhật vào tệp ở bước cuối cùng.

## Mẹo Tạo Bộ Đánh Giá Chất Lượng Cao

1. **Suy Nghĩ Kỹ và Lập Kế Hoạch Trước** khi bắt tay vào sinh câu hỏi
2. **Song Song Hóa Ở Những Nơi Có Thể** để tăng tốc quy trình và quản lý tốt cửa sổ ngữ cảnh
3. **Tập Trung Vào Các Trường Hợp Sử Dụng Thực Tế** mà con người thực sự muốn thực hiện
4. **Tạo Các Câu Hỏi Đầy Thử Thách** nhằm kiểm tra tới hạn năng lực của máy chủ MCP
5. **Đảm Bảo Tính Ổn Định** bằng cách sử dụng dữ liệu lịch sử và các sự kiện đã khép lại
6. **Xác Minh Đáp Án** bằng cách tự mình giải từng câu hỏi thông qua các công cụ của máy chủ MCP
7. **Lặp Lại và Tinh Chỉnh** dựa trên những gì bạn phát hiện được trong suốt quá trình thực hiện

---

# Chạy Đánh Giá (Running Evaluations)

Sau khi tạo xong tệp đánh giá, bạn có thể sử dụng bộ khung chạy kiểm thử (evaluation harness) được cung cấp sẵn để kiểm tra máy chủ MCP của mình.

## Thiết Lập Môi Trường

1. **Cài Đặt Các Thư Viện Phụ Thuộc**

   ```bash
   pip install -r scripts/requirements.txt
   ```

   Hoặc cài đặt thủ công:
   ```bash
   pip install anthropic mcp
   ```

2. **Thiết Lập Khóa API (API Key)**

   ```bash
   export ANTHROPIC_API_KEY=your_api_key_here
   ```

## Định Dạng Tệp Đánh Giá

Các tệp đánh giá sử dụng định dạng XML với các phần tử `<qa_pair>`:

```xml
<evaluation>
   <qa_pair>
      <question>Find the project created in Q2 2024 with the highest number of completed tasks. What is the project name?</question>
      <answer>Website Redesign</answer>
   </qa_pair>
   <qa_pair>
      <question>Search for issues labeled as "bug" that were closed in March 2024. Which user closed the most issues? Provide their username.</question>
      <answer>sarah_dev</answer>
   </qa_pair>
</evaluation>
```

## Cách Chạy Đánh Giá

Kịch bản chạy đánh giá (`scripts/evaluation.py`) hỗ trợ ba loại phương thức truyền tải:

**Quan trọng:**
- **Phương thức truyền tải stdio**: Kịch bản đánh giá sẽ tự động khởi chạy và quản lý tiến trình máy chủ MCP giúp bạn. Không cần tự chạy máy chủ thủ công.
- **Phương thức truyền tải sse/http**: Bạn bắt buộc phải khởi chạy máy chủ MCP riêng từ trước khi chạy kịch bản đánh giá. Kịch bản sẽ kết nối tới máy chủ đang chạy sẵn tại địa chỉ URL được chỉ định.

### 1. Máy Chủ STDIO Cục Bộ (Local STDIO Server)

Đối với các máy chủ MCP chạy cục bộ (kịch bản sẽ tự động khởi chạy máy chủ):

```bash
python scripts/evaluation.py \
  -t stdio \
  -c python \
  -a my_mcp_server.py \
  evaluation.xml
```

Khi cần truyền thêm các biến môi trường:
```bash
python scripts/evaluation.py \
  -t stdio \
  -c python \
  -a my_mcp_server.py \
  -e API_KEY=abc123 \
  -e DEBUG=true \
  evaluation.xml
```

### 2. Server-Sent Events (SSE)

Đối với các máy chủ MCP dựa trên SSE (bạn phải tự khởi chạy máy chủ trước):

```bash
python scripts/evaluation.py \
  -t sse \
  -u https://example.com/mcp \
  -H "Authorization: Bearer token123" \
  -H "X-Custom-Header: value" \
  evaluation.xml
```

### 3. HTTP (Streamable HTTP)

Đối với các máy chủ MCP dựa trên HTTP (bạn phải tự khởi chạy máy chủ trước):

```bash
python scripts/evaluation.py \
  -t http \
  -u https://example.com/mcp \
  -H "Authorization: Bearer token123" \
  evaluation.xml
```

## Các Tùy Chọn Dòng Lệnh (Command-Line Options)

```
usage: evaluation.py [-h] [-t {stdio,sse,http}] [-m MODEL] [-c COMMAND]
                     [-a ARGS [ARGS ...]] [-e ENV [ENV ...]] [-u URL]
                     [-H HEADERS [HEADERS ...]] [-o OUTPUT]
                     eval_file

positional arguments:
  eval_file             Path to evaluation XML file

optional arguments:
  -h, --help            Show help message
  -t, --transport       Transport type: stdio, sse, or http (default: stdio)
  -m, --model           Claude model to use (default: claude-3-7-sonnet-20250219)
  -o, --output          Output file for report (default: print to stdout)

stdio options:
  -c, --command         Command to run MCP server (e.g., python, node)
  -a, --args            Arguments for the command (e.g., server.py)
  -e, --env             Environment variables in KEY=VALUE format

sse/http options:
  -u, --url             MCP server URL
  -H, --header          HTTP headers in 'Key: Value' format
```

## Kết Quả Đầu Ra (Output)

Kịch bản đánh giá (evaluation script) sẽ tạo ra một báo cáo chi tiết bao gồm:

- **Thống kê Tóm tắt (Summary Statistics)**:
  - Độ chính xác (số câu đúng / tổng số câu)
  - Thời lượng thực hiện nhiệm vụ trung bình
  - Số lần gọi công cụ (tool calls) trung bình trên mỗi nhiệm vụ
  - Tổng số lần gọi công cụ

- **Kết quả Theo Từng Nhiệm vụ (Per-Task Results)**:
  - Prompt đầu vào và câu trả lời kỳ vọng
  - Câu trả lời thực tế từ tác tử (agent)
  - Câu trả lời đúng hay sai (✅/❌)
  - Thời gian thực thi và chi tiết các lệnh gọi công cụ
  - Bản tóm tắt của tác tử về hướng tiếp cận đã dùng
  - Phản hồi góp ý của tác tử về các công cụ

### Lưu Báo Cáo Ra Tệp

```bash
python scripts/evaluation.py \
  -t stdio \
  -c python \
  -a my_server.py \
  -o evaluation_report.md \
  evaluation.xml
```

## Ví Dụ Quy Trình Làm Việc Hoàn Chỉnh

Dưới đây là một ví dụ hoàn chỉnh về cách tạo và chạy một bộ đánh giá:

1. **Tạo tệp đánh giá của bạn** (`my_evaluation.xml`):

```xml
<evaluation>
   <qa_pair>
      <question>Find the user who created the most issues in January 2024. What is their username?</question>
      <answer>alice_developer</answer>
   </qa_pair>
   <qa_pair>
      <question>Among all pull requests merged in Q1 2024, which repository had the highest number? Provide the repository name.</question>
      <answer>backend-api</answer>
   </qa_pair>
   <qa_pair>
      <question>Find the project that was completed in December 2023 and had the longest duration from start to finish. How many days did it take?</question>
      <answer>127</answer>
   </qa_pair>
</evaluation>
```

2. **Cài đặt các thư viện phụ thuộc**:

```bash
pip install -r scripts/requirements.txt
export ANTHROPIC_API_KEY=your_api_key
```

3. **Chạy đánh giá**:

```bash
python scripts/evaluation.py \
  -t stdio \
  -c python \
  -a github_mcp_server.py \
  -e GITHUB_TOKEN=ghp_xxx \
  -o github_eval_report.md \
  my_evaluation.xml
```

4. **Xem xét báo cáo** trong tệp `github_eval_report.md` để:
   - Xem những câu hỏi nào đạt/không đạt
   - Đọc phản hồi của tác tử về bộ công cụ của bạn
   - Xác định những điểm cần cải thiện
   - Tinh chỉnh lặp lại thiết kế máy chủ MCP của bạn

## Xử Lý Sự Cố (Troubleshooting)

### Lỗi Kết Nối (Connection Errors)

Nếu bạn gặp lỗi kết nối:
- **STDIO**: Xác minh câu lệnh và các đối số truyền vào đã chính xác chưa
- **SSE/HTTP**: Kiểm tra xem URL có truy cập được không và các HTTP header đã đúng chưa
- Đảm bảo mọi khóa API bắt buộc đều đã được thiết lập trong biến môi trường hoặc headers

### Độ Chính Xác Thấp (Low Accuracy)

Nếu nhiều bài đánh giá bị thất bại:
- Xem xét kỹ phản hồi của tác tử cho từng nhiệm vụ
- Kiểm tra xem mô tả công cụ đã rõ ràng và toàn diện chưa
- Xác minh các tham số đầu vào đã được viết tài liệu hướng dẫn đầy đủ chưa
- Cân nhắc xem các công cụ có đang trả về quá nhiều hay quá ít dữ liệu không
- Đảm bảo các thông báo lỗi đều mang tính định hướng hành động (actionable)

### Vấn Đề Quá Thời Gian Chờ (Timeout Issues)

Nếu các nhiệm vụ bị quá thời gian chờ (timeout):
- Sử dụng một mô hình có năng lực cao hơn (ví dụ: `claude-3-7-sonnet-20250219`)
- Kiểm tra xem các công cụ có đang trả về khối lượng dữ liệu quá lớn không
- Xác minh cơ chế phân trang (pagination) đang hoạt động chính xác
- Cân nhắc đơn giản hóa các câu hỏi quá phức tạp
FILE:reference/node_mcp_server.md
# Hướng Dẫn Triển Khai Máy Chủ MCP Bằng Node/TypeScript

## Tổng Quan

Tài liệu này cung cấp các thông lệ tốt nhất và ví dụ chuyên biệt cho Node/TypeScript để triển khai máy chủ MCP bằng bộ công cụ MCP TypeScript SDK. Tài liệu bao quát cấu trúc dự án, thiết lập máy chủ, các mẫu đăng ký công cụ, xác thực đầu vào bằng Zod, xử lý lỗi và các ví dụ hoạt động hoàn chỉnh.

---

## Tham Chiếu Nhanh (Quick Reference)

### Các Lệnh Import Chính
```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import express from "express";
import { z } from "zod";
```

### Khởi Tạo Máy Chủ
```typescript
const server = new McpServer({
  name: "service-mcp-server",
  version: "1.0.0"
});
```

### Mẫu Đăng Ký Công Cụ (Tool Registration Pattern)
```typescript
server.registerTool(
  "tool_name",
  {
    title: "Tool Display Name",
    description: "What the tool does",
    inputSchema: { param: z.string() },
    outputSchema: { result: z.string() }
  },
  async ({ param }) => {
    const output = { result: `Processed: param` };
    return {
      content: [{ type: "text", text: JSON.stringify(output) }],
      structuredContent: output // Modern pattern for structured data
    };
  }
);
```

---

## Bộ Công Cụ MCP TypeScript SDK

MCP TypeScript SDK chính thức cung cấp:
- Lớp `McpServer` để khởi tạo máy chủ
- Phương thức `registerTool` để đăng ký công cụ
- Tích hợp lược đồ Zod để xác thực dữ liệu đầu vào lúc chạy (runtime)
- Triển khai hàm xử lý công cụ (tool handler) an toàn về kiểu dữ liệu (type-safe)

**QUAN TRỌNG - Chỉ Sử Dụng Các API Hiện Đại:**
- **NÊN dùng**: `server.registerTool()`, `server.registerResource()`, `server.registerPrompt()`
- **KHÔNG ĐƯỢC dùng**: Các API cũ đã lỗi thời (deprecated) như `server.tool()`, `server.setRequestHandler(ListToolsRequestSchema, ...)`, hoặc đăng ký hàm xử lý thủ công
- Các phương thức `register*` mang lại độ an toàn kiểu tốt hơn, tự động xử lý lược đồ và là cách tiếp cận được khuyến nghị chính thức

Xem tài liệu MCP SDK trong phần tài liệu tham khảo để biết chi tiết đầy đủ.

## Quy Ước Đặt Tên Máy Chủ

Các máy chủ MCP viết bằng Node/TypeScript phải tuân theo quy tắc đặt tên sau:
- **Định dạng**: `{service}-mcp-server` (chữ thường, nối bằng dấu gạch ngang)
- **Ví dụ**: `github-mcp-server`, `jira-mcp-server`, `stripe-mcp-server`

Tên máy chủ cần phải:
- Mang tính tổng quát (không gắn chặt vào một tính năng đơn lẻ cụ thể)
- Mô tả rõ dịch vụ/API đang được tích hợp
- Dễ dàng suy luận ra từ mô tả nhiệm vụ
- Không chứa số phiên bản hoặc ngày tháng

## Cấu Trúc Dự Án

Hãy tạo cấu trúc thư mục sau cho các máy chủ MCP dùng Node/TypeScript:

```
{service}-mcp-server/
├── package.json
├── tsconfig.json
├── README.md
├── src/
│   ├── index.ts          # Điểm vào chính chứa phần khởi tạo McpServer
│   ├── types.ts          # Định nghĩa các kiểu dữ liệu và interface TypeScript
│   ├── tools/            # Triển khai các công cụ (mỗi miền nghiệp vụ một tệp)
│   ├── services/         # Các API client và hàm tiện ích dùng chung
│   ├── schemas/          # Các lược đồ xác thực Zod
│   └── constants.ts      # Các hằng số dùng chung (API_URL, CHARACTER_LIMIT, v.v.)
└── dist/                 # Các tệp JavaScript đã biên dịch (điểm vào: dist/index.js)
```

## Triển Khai Công Cụ (Tool Implementation)

### Đặt Tên Công Cụ

Sử dụng kiểu chữ `snake_case` cho tên công cụ (ví dụ: "search_users", "create_project", "get_channel_info") với những cái tên rõ ràng, hướng hành động.

**Tránh Xung Đột Tên Gọi**: Đưa ngữ cảnh tên dịch vụ vào đầu tên công cụ để tránh trùng lặp:
- Dùng "slack_send_message" thay vì chỉ ghi "send_message"
- Dùng "github_create_issue" thay vì chỉ ghi "create_issue"
- Dùng "asana_list_tasks" thay vì chỉ ghi "list_tasks"

### Cấu Trúc Công Cụ

Các công cụ được đăng ký bằng phương thức `registerTool` với các yêu cầu sau:
- Sử dụng lược đồ Zod để xác thực đầu vào lúc chạy và đảm bảo an toàn kiểu
- Trường `description` phải được cung cấp tường minh - các chú thích JSDoc KHÔNG được tự động trích xuất
- Cung cấp tường minh các trường `title`, `description`, `inputSchema` và `annotations`
- Trường `inputSchema` phải là một đối tượng lược đồ Zod (không phải JSON schema)
- Định kiểu tường minh cho tất cả các tham số và giá trị trả về

```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({
  name: "example-mcp",
  version: "1.0.0"
});

// Zod schema for input validation
const UserSearchInputSchema = z.object({
  query: z.string()
    .min(2, "Query must be at least 2 characters")
    .max(200, "Query must not exceed 200 characters")
    .describe("Search string to match against names/emails"),
  limit: z.number()
    .int()
    .min(1)
    .max(100)
    .default(20)
    .describe("Maximum results to return"),
  offset: z.number()
    .int()
    .min(0)
    .default(0)
    .describe("Number of results to skip for pagination"),
  response_format: z.nativeEnum(ResponseFormat)
    .default(ResponseFormat.MARKDOWN)
    .describe("Output format: 'markdown' for human-readable or 'json' for machine-readable")
}).strict();

// Type definition from Zod schema
type UserSearchInput = z.infer<typeof UserSearchInputSchema>;

server.registerTool(
  "example_search_users",
  {
    title: "Search Example Users",
    description: `Search for users in the Example system by name, email, or team.

This tool searches across all user profiles in the Example platform, supporting partial matches and various search filters. It does NOT create or modify users, only searches existing ones.

Args:
  - query (string): Search string to match against names/emails
  - limit (number): Maximum results to return, between 1-100 (default: 20)
  - offset (number): Number of results to skip for pagination (default: 0)
  - response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns:
  For JSON format: Structured data with schema:
  {
    "total": number,           // Total number of matches found
    "count": number,           // Number of results in this response
    "offset": number,          // Current pagination offset
    "users": [
      {
        "id": string,          // User ID (e.g., "U123456789")
        "name": string,        // Full name (e.g., "John Doe")
        "email": string,       // Email address
        "team": string,        // Team name (optional)
        "active": boolean      // Whether user is active
      }
    ],
    "has_more": boolean,       // Whether more results are available
    "next_offset": number      // Offset for next page (if has_more is true)
  }

Examples:
  - Use when: "Find all marketing team members" -> params with query="team:marketing"
  - Use when: "Search for John's account" -> params with query="john"
  - Don't use when: You need to create a user (use example_create_user instead)

Error Handling:
  - Returns "Error: Rate limit exceeded" if too many requests (429 status)
  - Returns "No users found matching '<query>'" if search returns empty`,
    inputSchema: UserSearchInputSchema,
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: true
    }
  },
  async (params: UserSearchInput) => {
    try {
      // Input validation is handled by Zod schema
      // Make API request using validated parameters
      const data = await makeApiRequest<any>(
        "users/search",
        "GET",
        undefined,
        {
          q: params.query,
          limit: params.limit,
          offset: params.offset
        }
      );

      const users = data.users || [];
      const total = data.total || 0;

      if (!users.length) {
        return {
          content: [{
            type: "text",
            text: `No users found matching 'params.query'`
          }]
        };
      }

      // Prepare structured output
      const output = {
        total,
        count: users.length,
        offset: params.offset,
        users: users.map((user: any) => ({
          id: user.id,
          name: user.name,
          email: user.email,
          ...(user.team ? { team: user.team } : {}),
          active: user.active ?? true
        })),
        has_more: total > params.offset + users.length,
        ...(total > params.offset + users.length ? {
          next_offset: params.offset + users.length
        } : {})
      };

      // Format text representation based on requested format
      let textContent: string;
      if (params.response_format === ResponseFormat.MARKDOWN) {
        const lines = [`# User Search Results: 'params.query'`, "",
          `Found total users (showing users.length)`, ""];
        for (const user of users) {
          lines.push(`## user.name (user.id)`);
          lines.push(`- **Email**: user.email`);
          if (user.team) lines.push(`- **Team**: user.team`);
          lines.push("");
        }
        textContent = lines.join("\n");
      } else {
        textContent = JSON.stringify(output, null, 2);
      }

      return {
        content: [{ type: "text", text: textContent }],
        structuredContent: output // Modern pattern for structured data
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: handleApiError(error)
        }]
      };
    }
  }
);
```

## Lược Đồ Zod Cho Việc Xác Thực Đầu Vào

Zod cung cấp khả năng xác thực kiểu dữ liệu ngay trong lúc chạy (runtime):

```typescript
import { z } from "zod";

// Basic schema with validation
const CreateUserSchema = z.object({
  name: z.string()
    .min(1, "Name is required")
    .max(100, "Name must not exceed 100 characters"),
  email: z.string()
    .email("Invalid email format"),
  age: z.number()
    .int("Age must be a whole number")
    .min(0, "Age cannot be negative")
    .max(150, "Age cannot be greater than 150")
}).strict();  // Use .strict() to forbid extra fields

// Enums
enum ResponseFormat {
  MARKDOWN = "markdown",
  JSON = "json"
}

const SearchSchema = z.object({
  response_format: z.nativeEnum(ResponseFormat)
    .default(ResponseFormat.MARKDOWN)
    .describe("Output format")
});

// Optional fields with defaults
const PaginationSchema = z.object({
  limit: z.number()
    .int()
    .min(1)
    .max(100)
    .default(20)
    .describe("Maximum results to return"),
  offset: z.number()
    .int()
    .min(0)
    .default(0)
    .describe("Number of results to skip")
});
```

## Các Tùy Chọn Định Dạng Phản Hồi

Hỗ trợ nhiều định dạng đầu ra để đảm bảo tính linh hoạt:

```typescript
enum ResponseFormat {
  MARKDOWN = "markdown",
  JSON = "json"
}

const inputSchema = z.object({
  query: z.string(),
  response_format: z.nativeEnum(ResponseFormat)
    .default(ResponseFormat.MARKDOWN)
    .describe("Output format: 'markdown' for human-readable or 'json' for machine-readable")
});
```

**Định dạng Markdown**:
- Sử dụng tiêu đề, danh sách và định dạng văn bản để trình bày rõ ràng
- Chuyển đổi dấu thời gian (timestamps) sang định dạng dễ đọc cho con người
- Hiển thị tên hiển thị kèm theo mã ID đặt trong dấu ngoặc đơn
- Lược bỏ các siêu dữ liệu (metadata) rườm rà
- Gom nhóm các thông tin liên quan một cách hợp lý

**Định dạng JSON**:
- Trả về dữ liệu đầy đủ, có cấu trúc phù hợp cho việc xử lý bằng mã lệnh (programmatic processing)
- Bao gồm tất cả các trường và siêu dữ liệu hiện có
- Sử dụng tên trường và kiểu dữ liệu nhất quán

## Triển Khai Phân Trang (Pagination)

Đối với các công cụ liệt kê danh sách tài nguyên:

```typescript
const ListSchema = z.object({
  limit: z.number().int().min(1).max(100).default(20),
  offset: z.number().int().min(0).default(0)
});

async function listItems(params: z.infer<typeof ListSchema>) {
  const data = await apiRequest(params.limit, params.offset);

  const response = {
    total: data.total,
    count: data.items.length,
    offset: params.offset,
    items: data.items,
    has_more: data.total > params.offset + data.items.length,
    next_offset: data.total > params.offset + data.items.length
      ? params.offset + data.items.length
      : undefined
  };

  return JSON.stringify(response, null, 2);
}
```

## Giới Hạn Ký Tự Và Cắt Ngắn Dữ Liệu (Truncation)

Thêm hằng số `CHARACTER_LIMIT` để ngăn chặn các phản hồi quá lớn làm tràn ngữ cảnh:

```typescript
// At module level in constants.ts
export const CHARACTER_LIMIT = 25000;  // Maximum response size in characters

async function searchTool(params: SearchInput) {
  let result = generateResponse(data);

  // Check character limit and truncate if needed
  if (result.length > CHARACTER_LIMIT) {
    const truncatedData = data.slice(0, Math.max(1, data.length / 2));
    response.data = truncatedData;
    response.truncated = true;
    response.truncation_message =
      `Response truncated from data.length to truncatedData.length items. ` +
      `Use 'offset' parameter or add filters to see more results.`;
    result = JSON.stringify(response, null, 2);
  }

  return result;
}
```

## Xử Lý Lỗi (Error Handling)

Cung cấp các thông báo lỗi rõ ràng, có tính định hướng hành động:

```typescript
import axios, { AxiosError } from "axios";

function handleApiError(error: unknown): string {
  if (error instanceof AxiosError) {
    if (error.response) {
      switch (error.response.status) {
        case 404:
          return "Error: Resource not found. Please check the ID is correct.";
        case 403:
          return "Error: Permission denied. You don't have access to this resource.";
        case 429:
          return "Error: Rate limit exceeded. Please wait before making more requests.";
        default:
          return `Error: API request failed with status error.response.status`;
      }
    } else if (error.code === "ECONNABORTED") {
      return "Error: Request timed out. Please try again.";
    }
  }
  return `Error: Unexpected error occurred: String(error)`;
}
```

## Các Hàm Tiện Ích Dùng Chung (Shared Utilities)

Tách các chức năng phổ biến thành các hàm có thể tái sử dụng:

```typescript
// Shared API request function
async function makeApiRequest<T>(
  endpoint: string,
  method: "GET" | "POST" | "PUT" | "DELETE" = "GET",
  data?: any,
  params?: any
): Promise<T> {
  try {
    const response = await axios({
      method,
      url: `API_BASE_URL/endpoint`,
      data,
      params,
      timeout: 30000,
      headers: {
        "Content-Type": "application/json",
        "Accept": "application/json"
      }
    });
    return response.data;
  } catch (error) {
    throw error;
  }
}
```

## Thông Lệ Tốt Nhất Với Async/Await

Luôn sử dụng `async/await` cho các yêu cầu mạng và thao tác vào/ra (I/O):

```typescript
// Good: Async network request
async function fetchData(resourceId: string): Promise<ResourceData> {
  const response = await axios.get(`API_URL/resource/resourceId`);
  return response.data;
}

// Bad: Promise chains
function fetchData(resourceId: string): Promise<ResourceData> {
  return axios.get(`API_URL/resource/resourceId`)
    .then(response => response.data);  // Harder to read and maintain
}
```

## Các Thông Lệ Tốt Nhất Với TypeScript

1. **Sử dụng TypeScript Nghiêm ngặt (Strict TypeScript)**: Bật chế độ `strict` trong tệp `tsconfig.json`
2. **Định nghĩa Interfaces**: Tạo các định nghĩa `interface` rõ ràng cho mọi cấu trúc dữ liệu
3. **Tránh dùng `any`**: Sử dụng các kiểu dữ liệu chuẩn xác hoặc `unknown` thay cho `any`
4. **Dùng Zod để Xác thực Lúc chạy**: Sử dụng lược đồ Zod để xác thực dữ liệu từ nguồn bên ngoài
5. **Bộ bảo vệ kiểu (Type Guards)**: Tạo các hàm type guard để kiểm tra các kiểu dữ liệu phức tạp
6. **Xử lý lỗi**: Luôn sử dụng khối `try-catch` kèm theo bước kiểm tra kiểu lỗi chuẩn xác
7. **An toàn với giá trị Null (Null Safety)**: Sử dụng toán tử truy cập chuỗi tùy chọn (`?.`) và toán tử hợp nhất null (`??`)

```typescript
// Good: Type-safe with Zod and interfaces
interface UserResponse {
  id: string;
  name: string;
  email: string;
  team?: string;
  active: boolean;
}

const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
  team: z.string().optional(),
  active: z.boolean()
});

type User = z.infer<typeof UserSchema>;

async function getUser(id: string): Promise<User> {
  const data = await apiCall(`/users/id`);
  return UserSchema.parse(data);  // Runtime validation
}

// Bad: Using any
async function getUser(id: string): Promise<any> {
  return await apiCall(`/users/id`);  // No type safety
}
```

## Cấu Hình Gói Dự Án (Package Configuration)

### package.json

```json
{
  "name": "{service}-mcp-server",
  "version": "1.0.0",
  "description": "MCP server for {Service} API integration",
  "type": "module",
  "main": "dist/index.js",
  "scripts": {
    "start": "node dist/index.js",
    "dev": "tsx watch src/index.ts",
    "build": "tsc",
    "clean": "rm -rf dist"
  },
  "engines": {
    "node": ">=18"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.6.1",
    "axios": "^1.7.9",
    "zod": "^3.23.8"
  },
  "devDependencies": {
    "@types/node": "^22.10.0",
    "tsx": "^4.19.2",
    "typescript": "^5.7.2"
  }
}
```

### tsconfig.json

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "lib": ["ES2022"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "allowSyntheticDefaultImports": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

## Ví Dụ Hoàn Chỉnh

```typescript
#!/usr/bin/env node
/**
 * MCP Server for Example Service.
 *
 * This server provides tools to interact with Example API, including user search,
 * project management, and data export capabilities.
 */

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import axios, { AxiosError } from "axios";

// Constants
const API_BASE_URL = "https://api.example.com/v1";
const CHARACTER_LIMIT = 25000;

// Enums
enum ResponseFormat {
  MARKDOWN = "markdown",
  JSON = "json"
}

// Zod schemas
const UserSearchInputSchema = z.object({
  query: z.string()
    .min(2, "Query must be at least 2 characters")
    .max(200, "Query must not exceed 200 characters")
    .describe("Search string to match against names/emails"),
  limit: z.number()
    .int()
    .min(1)
    .max(100)
    .default(20)
    .describe("Maximum results to return"),
  offset: z.number()
    .int()
    .min(0)
    .default(0)
    .describe("Number of results to skip for pagination"),
  response_format: z.nativeEnum(ResponseFormat)
    .default(ResponseFormat.MARKDOWN)
    .describe("Output format: 'markdown' for human-readable or 'json' for machine-readable")
}).strict();

type UserSearchInput = z.infer<typeof UserSearchInputSchema>;

// Shared utility functions
async function makeApiRequest<T>(
  endpoint: string,
  method: "GET" | "POST" | "PUT" | "DELETE" = "GET",
  data?: any,
  params?: any
): Promise<T> {
  try {
    const response = await axios({
      method,
      url: `API_BASE_URL/endpoint`,
      data,
      params,
      timeout: 30000,
      headers: {
        "Content-Type": "application/json",
        "Accept": "application/json"
      }
    });
    return response.data;
  } catch (error) {
    throw error;
  }
}

function handleApiError(error: unknown): string {
  if (error instanceof AxiosError) {
    if (error.response) {
      switch (error.response.status) {
        case 404:
          return "Error: Resource not found. Please check the ID is correct.";
        case 403:
          return "Error: Permission denied. You don't have access to this resource.";
        case 429:
          return "Error: Rate limit exceeded. Please wait before making more requests.";
        default:
          return `Error: API request failed with status error.response.status`;
      }
    } else if (error.code === "ECONNABORTED") {
      return "Error: Request timed out. Please try again.";
    }
  }
  return `Error: Unexpected error occurred: String(error)`;
}

// Create MCP server instance
const server = new McpServer({
  name: "example-mcp",
  version: "1.0.0"
});

// Register tools
server.registerTool(
  "example_search_users",
  {
    title: "Search Example Users",
    description: `[Full description as shown above]`,
    inputSchema: UserSearchInputSchema,
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: true
    }
  },
  async (params: UserSearchInput) => {
    // Implementation as shown above
  }
);

// Main function
// For stdio (local):
async function runStdio() {
  if (!process.env.EXAMPLE_API_KEY) {
    console.error("ERROR: EXAMPLE_API_KEY environment variable is required");
    process.exit(1);
  }

  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("MCP server running via stdio");
}

// For streamable HTTP (remote):
async function runHTTP() {
  if (!process.env.EXAMPLE_API_KEY) {
    console.error("ERROR: EXAMPLE_API_KEY environment variable is required");
    process.exit(1);
  }

  const app = express();
  app.use(express.json());

  app.post('/mcp', async (req, res) => {
    const transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: undefined,
      enableJsonResponse: true
    });
    res.on('close', () => transport.close());
    await server.connect(transport);
    await transport.handleRequest(req, res, req.body);
  });

  const port = parseInt(process.env.PORT || '3000');
  app.listen(port, () => {
    console.error(`MCP server running on http://localhost:port/mcp`);
  });
}

// Choose transport based on environment
const transport = process.env.TRANSPORT || 'stdio';
if (transport === 'http') {
  runHTTP().catch(error => {
    console.error("Server error:", error);
    process.exit(1);
  });
} else {
  runStdio().catch(error => {
    console.error("Server error:", error);
    process.exit(1);
  });
}
```

---

## Các Tính Năng MCP Nâng Cao

### Đăng Ký Tài Nguyên (Resource Registration)

Phơi bày dữ liệu dưới dạng các tài nguyên (resources) để truy cập hiệu quả dựa trên đường dẫn URI:

```typescript
import { ResourceTemplate } from "@modelcontextprotocol/sdk/types.js";

// Register a resource with URI template
server.registerResource(
  {
    uri: "file://documents/{name}",
    name: "Document Resource",
    description: "Access documents by name",
    mimeType: "text/plain"
  },
  async (uri: string) => {
    // Extract parameter from URI
    const match = uri.match(/^file:\/\/documents\/(.+)$/);
    if (!match) {
      throw new Error("Invalid URI format");
    }

    const documentName = match[1];
    const content = await loadDocument(documentName);

    return {
      contents: [{
        uri,
        mimeType: "text/plain",
        text: content
      }]
    };
  }
);

// List available resources dynamically
server.registerResourceList(async () => {
  const documents = await getAvailableDocuments();
  return {
    resources: documents.map(doc => ({
      uri: `file://documents/doc.name`,
      name: doc.name,
      mimeType: "text/plain",
      description: doc.description
    }))
  };
});
```

**Khi nào nên dùng Resources so với Tools:**
- **Resources**: Dành cho việc truy cập dữ liệu với các tham số đơn giản dựa trên URI
- **Tools**: Dành cho các thao tác phức tạp đòi hỏi xác thực đầu vào và xử lý logic nghiệp vụ
- **Resources**: Khi dữ liệu mang tính tĩnh tương đối hoặc dựa trên khuôn mẫu (template-based)
- **Tools**: Khi thao tác tạo ra tác dụng phụ (side effects) hoặc gồm các luồng công việc phức tạp

### Các Tùy Chọn Truyền Tải (Transport Options)

Bộ công cụ TypeScript SDK hỗ trợ hai cơ chế truyền tải chính:

#### Streamable HTTP (Khuyến nghị cho các Máy chủ Từ xa)

```typescript
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import express from "express";

const app = express();
app.use(express.json());

app.post('/mcp', async (req, res) => {
  // Create new transport for each request (stateless, prevents request ID collisions)
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
    enableJsonResponse: true
  });

  res.on('close', () => transport.close());

  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

app.listen(3000);
```

#### stdio (Dành cho Tích hợp Cục bộ)

```typescript
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const transport = new StdioServerTransport();
await server.connect(transport);
```

**Lựa chọn phương thức truyền tải:**
- **Streamable HTTP**: Dịch vụ web, truy cập từ xa, phục vụ nhiều ứng dụng khách (clients) cùng lúc
- **stdio**: Công cụ dòng lệnh, phát triển cục bộ, tích hợp dưới dạng tiến trình con (subprocess)

### Hỗ Trợ Thông Báo (Notification Support)

Thông báo cho phía client khi trạng thái của máy chủ thay đổi:

```typescript
// Notify when tools list changes
server.notification({
  method: "notifications/tools/list_changed"
});

// Notify when resources change
server.notification({
  method: "notifications/resources/list_changed"
});
```

Hãy sử dụng thông báo một cách tiết chế - chỉ gửi khi năng lực (capabilities) của máy chủ thực sự thay đổi.

---

## Các Thông Lệ Tốt Nhất Về Mã Nguồn

### Khả Năng Kết Hợp Và Tái Sử Dụng Mã Nguồn (Code Composability and Reusability)

Bản triển khai của bạn BẮT BUỘC phải ưu tiên tính kết hợp và khả năng tái sử dụng mã nguồn:

1. **Tách Các Chức Năng Chung**:
   - Tạo các hàm bổ trợ (helper functions) tái sử dụng được cho những thao tác xuất hiện ở nhiều công cụ
   - Xây dựng các API client dùng chung cho các yêu cầu HTTP thay vì viết lặp lại mã nguồn
   - Tập trung hóa logic xử lý lỗi vào các hàm tiện ích
   - Tách logic nghiệp vụ vào các hàm chuyên biệt có thể kết hợp lại với nhau
   - Tách riêng chức năng chọn lọc trường dữ liệu & định dạng kết quả Markdown hoặc JSON dùng chung

2. **Tránh Trùng Lặp Mã Nguồn**:
   - KHÔNG BAO GIỜ sao chép-dán (copy-paste) các đoạn mã tương tự nhau giữa các công cụ
   - Nếu bạn thấy mình đang viết một logic tương tự đến lần thứ hai, hãy tách nó thành một hàm dùng chung
   - Các thao tác phổ biến như phân trang, lọc dữ liệu, chọn trường và định dạng kết quả cần được chia sẻ chung
   - Logic xác thực và phân quyền cần được tập trung hóa ở một nơi

## Biên Dịch Và Chạy Thử (Building and Running)

Luôn biên dịch mã TypeScript của bạn trước khi chạy:

```bash
# Build the project
npm run build

# Run the server
npm start

# Development with auto-reload
npm run dev
```

Luôn đảm bảo lệnh `npm run build` hoàn tất thành công trước khi coi bản triển khai là đã hoàn thành.

## Danh Sách Kiểm Tra Chất Lượng (Quality Checklist)

Trước khi hoàn tất việc triển khai máy chủ MCP bằng Node/TypeScript, hãy đảm bảo:

### Thiết Kế Chiến Lược (Strategic Design)
- [ ] Các công cụ hỗ trợ thực hiện các luồng công việc hoàn chỉnh, chứ không chỉ là lớp vỏ bọc mỏng quanh các điểm cuối API
- [ ] Tên công cụ phản ánh sự phân chia tác vụ một cách tự nhiên
- [ ] Định dạng phản hồi được tối ưu hóa để tiết kiệm ngữ cảnh (context efficiency) cho tác tử
- [ ] Sử dụng các mã định danh dễ đọc cho con người ở những chỗ phù hợp
- [ ] Thông báo lỗi hướng dẫn tác tử đi tới cách sử dụng đúng

### Chất Lượng Triển Khai (Implementation Quality)
- [ ] TRIỂN KHAI CÓ TRỌNG TÂM: Đã triển khai các công cụ quan trọng và mang lại nhiều giá trị nhất
- [ ] Tất cả công cụ đều được đăng ký bằng `registerTool` với cấu hình đầy đủ
- [ ] Tất cả công cụ đều bao gồm `title`, `description`, `inputSchema` và `annotations`
- [ ] Các chú thích (`annotations`) được thiết lập chính xác (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`)
- [ ] Tất cả công cụ đều sử dụng lược đồ Zod để xác thực đầu vào lúc chạy kèm theo ràng buộc `.strict()`
- [ ] Tất cả lược đồ Zod đều có các ràng buộc hợp lý và thông báo lỗi giàu tính mô tả
- [ ] Tất cả công cụ đều có mô tả toàn diện với kiểu đầu vào/đầu ra tường minh
- [ ] Phần mô tả bao gồm các ví dụ về giá trị trả về và tài liệu lược đồ đầy đủ
- [ ] Các thông báo lỗi rõ ràng, có tính hành động và mang tính hướng dẫn cao

### Chất Lượng TypeScript (TypeScript Quality)
- [ ] Các interface TypeScript được định nghĩa cho toàn bộ các cấu trúc dữ liệu
- [ ] Chế độ Strict TypeScript được bật trong `tsconfig.json`
- [ ] Không sử dụng kiểu `any` - hãy dùng `unknown` hoặc các kiểu dữ liệu cụ thể để thay thế
- [ ] Tất cả các hàm `async` đều khai báo kiểu trả về `Promise<T>` tường minh
- [ ] Việc xử lý lỗi sử dụng các bộ bảo vệ kiểu (type guards) chuẩn xác (ví dụ: `axios.isAxiosError`, `z.ZodError`)

### Các Tính Năng Nâng Cao (nếu áp dụng)
- [ ] Đã đăng ký Resources cho các điểm cuối dữ liệu phù hợp
- [ ] Đã cấu hình cơ chế truyền tải phù hợp (`stdio` hoặc `streamable HTTP`)
- [ ] Đã triển khai thông báo (Notifications) cho các năng lực máy chủ thay đổi động
- [ ] Đảm bảo an toàn kiểu với các interface của SDK

### Cấu Hình Dự Án (Project Configuration)
- [ ] Tệp `package.json` bao gồm đầy đủ tất cả các thư viện phụ thuộc cần thiết
- [ ] Kịch bản build tạo ra mã JavaScript hoạt động tốt trong thư mục `dist/`
- [ ] Điểm vào chính được cấu hình chuẩn xác là `dist/index.js`
- [ ] Tên máy chủ tuân thủ đúng định dạng: `{service}-mcp-server`
- [ ] Tệp `tsconfig.json` được cấu hình đúng chuẩn với chế độ `strict`

### Chất Lượng Mã Nguồn (Code Quality)
- [ ] Cơ chế phân trang được triển khai đúng cách ở những nơi cần thiết
- [ ] Các phản hồi lớn đều kiểm tra hằng số `CHARACTER_LIMIT` và cắt ngắn kèm theo thông báo rõ ràng
- [ ] Cung cấp các tùy chọn lọc (filtering) cho các tập kết quả có khả năng phình to
- [ ] Mọi thao tác mạng đều xử lý mượt mà lỗi quá thời gian chờ (timeouts) và lỗi kết nối
- [ ] Các chức năng chung được tách thành các hàm tái sử dụng
- [ ] Kiểu dữ liệu trả về nhất quán giữa các thao tác tương tự nhau

### Kiểm Thử Và Đóng Gói (Testing and Build)
- [ ] Lệnh `npm run build` chạy hoàn tất thành công không có lỗi
- [ ] Tệp `dist/index.js` được tạo ra và có thể thực thi
- [ ] Máy chủ chạy được với lệnh: `node dist/index.js --help`
- [ ] Tất cả các lệnh import đều phân giải đường dẫn chính xác
- [ ] Các lệnh gọi công cụ mẫu hoạt động đúng như kỳ vọng
FILE:reference/python_mcp_server.md
# Hướng Dẫn Triển Khai Máy Chủ MCP Bằng Python

## Tổng Quan

Tài liệu này cung cấp các thông lệ tốt nhất và ví dụ chuyên biệt cho Python để triển khai máy chủ MCP bằng bộ công cụ MCP Python SDK. Tài liệu bao quát việc thiết lập máy chủ, các mẫu đăng ký công cụ, xác thực đầu vào bằng Pydantic, xử lý lỗi và các ví dụ hoạt động hoàn chỉnh.

---

## Tham Chiếu Nhanh (Quick Reference)

### Các Lệnh Import Chính
```python
from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel, Field, field_validator, ConfigDict
from typing import Optional, List, Dict, Any
from enum import Enum
import httpx
```

### Khởi Tạo Máy Chủ
```python
mcp = FastMCP("service_mcp")
```

### Mẫu Đăng Ký Công Cụ (Tool Registration Pattern)
```python
@mcp.tool(name="tool_name", annotations={...})
async def tool_function(params: InputModel) -> str:
    # Implementation
    pass
```

---

## Bộ Công Cụ MCP Python SDK Và FastMCP

MCP Python SDK chính thức cung cấp FastMCP, một framework bậc cao để xây dựng các máy chủ MCP. Nó mang lại:
- Khả năng tự động sinh mô tả (`description`) và lược đồ đầu vào (`inputSchema`) từ chữ ký hàm (function signatures) và chuỗi tài liệu (docstrings)
- Tích hợp mô hình Pydantic để xác thực dữ liệu đầu vào
- Đăng ký công cụ dựa trên decorator với `@mcp.tool`

**Để xem toàn bộ tài liệu SDK đầy đủ, hãy dùng WebFetch để tải:**
`https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`

## Quy Ước Đặt Tên Máy Chủ

Các máy chủ MCP viết bằng Python phải tuân theo quy tắc đặt tên sau:
- **Định dạng**: `{service}_mcp` (chữ thường, nối bằng dấu gạch dưới)
- **Ví dụ**: `github_mcp`, `jira_mcp`, `stripe_mcp`

Tên máy chủ cần phải:
- Mang tính tổng quát (không gắn chặt vào một tính năng đơn lẻ cụ thể)
- Mô tả rõ dịch vụ/API đang được tích hợp
- Dễ dàng suy luận ra từ mô tả nhiệm vụ
- Không chứa số phiên bản hoặc ngày tháng

## Triển Khai Công Cụ (Tool Implementation)

### Đặt Tên Công Cụ

Sử dụng kiểu chữ `snake_case` cho tên công cụ (ví dụ: "search_users", "create_project", "get_channel_info") với những cái tên rõ ràng, hướng hành động.

**Tránh Xung Đột Tên Gọi**: Đưa ngữ cảnh tên dịch vụ vào đầu tên công cụ để tránh trùng lặp:
- Dùng "slack_send_message" thay vì chỉ ghi "send_message"
- Dùng "github_create_issue" thay vì chỉ ghi "create_issue"
- Dùng "asana_list_tasks" thay vì chỉ ghi "list_tasks"

### Cấu Trúc Công Cụ Với FastMCP

Các công cụ được định nghĩa bằng cách sử dụng decorator `@mcp.tool` kết hợp với các mô hình Pydantic để xác thực đầu vào:

```python
from pydantic import BaseModel, Field, ConfigDict
from mcp.server.fastmcp import FastMCP

# Initialize the MCP server
mcp = FastMCP("example_mcp")

# Define Pydantic model for input validation
class ServiceToolInput(BaseModel):
    '''Input model for service tool operation.'''
    model_config = ConfigDict(
        str_strip_whitespace=True,  # Auto-strip whitespace from strings
        validate_assignment=True,    # Validate on assignment
        extra='forbid'              # Forbid extra fields
    )

    param1: str = Field(..., description="First parameter description (e.g., 'user123', 'project-abc')", min_length=1, max_length=100)
    param2: Optional[int] = Field(default=None, description="Optional integer parameter with constraints", ge=0, le=1000)
    tags: Optional[List[str]] = Field(default_factory=list, description="List of tags to apply", max_items=10)

@mcp.tool(
    name="service_tool_name",
    annotations={
        "title": "Human-Readable Tool Title",
        "readOnlyHint": True,     # Tool does not modify environment
        "destructiveHint": False,  # Tool does not perform destructive operations
        "idempotentHint": True,    # Repeated calls have no additional effect
        "openWorldHint": False     # Tool does not interact with external entities
    }
)
async def service_tool_name(params: ServiceToolInput) -> str:
    '''Tool description automatically becomes the 'description' field.

    This tool performs a specific operation on the service. It validates all inputs
    using the ServiceToolInput Pydantic model before processing.

    Args:
        params (ServiceToolInput): Validated input parameters containing:
            - param1 (str): First parameter description
            - param2 (Optional[int]): Optional parameter with default
            - tags (Optional[List[str]]): List of tags

    Returns:
        str: JSON-formatted response containing operation results
    '''
    # Implementation here
    pass
```

## Các Tính Năng Chính Của Pydantic v2

- Sử dụng `model_config` thay cho lớp `Config` lồng bên trong
- Sử dụng `field_validator` thay cho `validator` đã lỗi thời
- Sử dụng `model_dump()` thay cho `dict()` đã lỗi thời
- Các hàm kiểm tra hợp lệ (validators) bắt buộc phải có decorator `@classmethod`
- Bắt buộc phải khai báo gợi ý kiểu (type hints) cho các phương thức validator

```python
from pydantic import BaseModel, Field, field_validator, ConfigDict

class CreateUserInput(BaseModel):
    model_config = ConfigDict(
        str_strip_whitespace=True,
        validate_assignment=True
    )

    name: str = Field(..., description="User's full name", min_length=1, max_length=100)
    email: str = Field(..., description="User's email address", pattern=r'^[\w\.-]+@[\w\.-]+\.\w+$')
    age: int = Field(..., description="User's age", ge=0, le=150)

    @field_validator('email')
    @classmethod
    def validate_email(cls, v: str) -> str:
        if not v.strip():
            raise ValueError("Email cannot be empty")
        return v.lower()
```

## Các Tùy Chọn Định Dạng Phản Hồi

Hỗ trợ nhiều định dạng đầu ra để đảm bảo tính linh hoạt:

```python
from enum import Enum

class ResponseFormat(str, Enum):
    '''Output format for tool responses.'''
    MARKDOWN = "markdown"
    JSON = "json"

class UserSearchInput(BaseModel):
    query: str = Field(..., description="Search query")
    response_format: ResponseFormat = Field(
        default=ResponseFormat.MARKDOWN,
        description="Output format: 'markdown' for human-readable or 'json' for machine-readable"
    )
```

**Định dạng Markdown**:
- Sử dụng tiêu đề, danh sách và định dạng văn bản để trình bày rõ ràng
- Chuyển đổi dấu thời gian sang định dạng dễ đọc cho con người (ví dụ: "2024-01-15 10:30:00 UTC" thay vì số giây epoch)
- Hiển thị tên hiển thị kèm theo mã ID đặt trong dấu ngoặc đơn (ví dụ: "@john.doe (U123456)")
- Lược bỏ các siêu dữ liệu (metadata) rườm rà (ví dụ: chỉ hiển thị một URL ảnh đại diện, không liệt kê tất cả các kích cỡ)
- Gom nhóm các thông tin liên quan một cách hợp lý

**Định dạng JSON**:
- Trả về dữ liệu đầy đủ, có cấu trúc phù hợp cho việc xử lý bằng mã lệnh (programmatic processing)
- Bao gồm tất cả các trường và siêu dữ liệu hiện có
- Sử dụng tên trường và kiểu dữ liệu nhất quán

## Triển Khai Phân Trang (Pagination Implementation)

Đối với các công cụ liệt kê danh sách tài nguyên:

```python
class ListInput(BaseModel):
    limit: Optional[int] = Field(default=20, description="Maximum results to return", ge=1, le=100)
    offset: Optional[int] = Field(default=0, description="Number of results to skip for pagination", ge=0)

async def list_items(params: ListInput) -> str:
    # Make API request with pagination
    data = await api_request(limit=params.limit, offset=params.offset)

    # Return pagination info
    response = {
        "total": data["total"],
        "count": len(data["items"]),
        "offset": params.offset,
        "items": data["items"],
        "has_more": data["total"] > params.offset + len(data["items"]),
        "next_offset": params.offset + len(data["items"]) if data["total"] > params.offset + len(data["items"]) else None
    }
    return json.dumps(response, indent=2)
```

## Xử Lý Lỗi (Error Handling)

Cung cấp các thông báo lỗi rõ ràng, có tính định hướng hành động:

```python
def _handle_api_error(e: Exception) -> str:
    '''Consistent error formatting across all tools.'''
    if isinstance(e, httpx.HTTPStatusError):
        if e.response.status_code == 404:
            return "Error: Resource not found. Please check the ID is correct."
        elif e.response.status_code == 403:
            return "Error: Permission denied. You don't have access to this resource."
        elif e.response.status_code == 429:
            return "Error: Rate limit exceeded. Please wait before making more requests."
        return f"Error: API request failed with status {e.response.status_code}"
    elif isinstance(e, httpx.TimeoutException):
        return "Error: Request timed out. Please try again."
    return f"Error: Unexpected error occurred: {type(e).__name__}"
```

## Các Hàm Tiện Ích Dùng Chung (Shared Utilities)

Tách các chức năng phổ biến thành các hàm có thể tái sử dụng:

```python
# Shared API request function
async def _make_api_request(endpoint: str, method: str = "GET", **kwargs) -> dict:
    '''Reusable function for all API calls.'''
    async with httpx.AsyncClient() as client:
        response = await client.request(
            method,
            f"{API_BASE_URL}/{endpoint}",
            timeout=30.0,
            **kwargs
        )
        response.raise_for_status()
        return response.json()
```

## Thông Lệ Tốt Nhất Với Async/Await

Luôn sử dụng `async/await` cho các yêu cầu mạng và thao tác vào/ra (I/O):

```python
# Good: Async network request
async def fetch_data(resource_id: str) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.get(f"{API_URL}/resource/{resource_id}")
        response.raise_for_status()
        return response.json()

# Bad: Synchronous request
def fetch_data(resource_id: str) -> dict:
    response = requests.get(f"{API_URL}/resource/{resource_id}")  # Blocks
    return response.json()
```

## Gợi Ý Kiểu Dữ Liệu (Type Hints)

Sử dụng gợi ý kiểu dữ liệu xuyên suốt toàn bộ mã nguồn:

```python
from typing import Optional, List, Dict, Any

async def get_user(user_id: str) -> Dict[str, Any]:
    data = await fetch_user(user_id)
    return {"id": data["id"], "name": data["name"]}
```

## Chuỗi Tài Liệu Của Công Cụ (Tool Docstrings)

Mọi công cụ đều phải có chuỗi tài liệu (docstrings) toàn diện với thông tin kiểu dữ liệu tường minh:

```python
async def search_users(params: UserSearchInput) -> str:
    '''
    Search for users in the Example system by name, email, or team.

    This tool searches across all user profiles in the Example platform,
    supporting partial matches and various search filters. It does NOT
    create or modify users, only searches existing ones.

    Args:
        params (UserSearchInput): Validated input parameters containing:
            - query (str): Search string to match against names/emails (e.g., "john", "@example.com", "team:marketing")
            - limit (Optional[int]): Maximum results to return, between 1-100 (default: 20)
            - offset (Optional[int]): Number of results to skip for pagination (default: 0)

    Returns:
        str: JSON-formatted string containing search results with the following schema:

        Success response:
        {
            "total": int,           # Total number of matches found
            "count": int,           # Number of results in this response
            "offset": int,          # Current pagination offset
            "users": [
                {
                    "id": str,      # User ID (e.g., "U123456789")
                    "name": str,    # Full name (e.g., "John Doe")
                    "email": str,   # Email address (e.g., "john@example.com")
                    "team": str     # Team name (e.g., "Marketing") - optional
                }
            ]
        }

        Error response:
        "Error: <error message>" or "No users found matching '<query>'"

    Examples:
        - Use when: "Find all marketing team members" -> params with query="team:marketing"
        - Use when: "Search for John's account" -> params with query="john"
        - Don't use when: You need to create a user (use example_create_user instead)
        - Don't use when: You have a user ID and need full details (use example_get_user instead)

    Error Handling:
        - Input validation errors are handled by Pydantic model
        - Returns "Error: Rate limit exceeded" if too many requests (429 status)
        - Returns "Error: Invalid API authentication" if API key is invalid (401 status)
        - Returns formatted list of results or "No users found matching 'query'"
    '''
```

## Ví Dụ Hoàn Chỉnh

Xem bên dưới để tham khảo một ví dụ máy chủ MCP viết bằng Python hoàn chỉnh:

```python
#!/usr/bin/env python3
'''
MCP Server for Example Service.

This server provides tools to interact with Example API, including user search,
project management, and data export capabilities.
'''

from typing import Optional, List, Dict, Any
from enum import Enum
import httpx
from pydantic import BaseModel, Field, field_validator, ConfigDict
from mcp.server.fastmcp import FastMCP

# Initialize the MCP server
mcp = FastMCP("example_mcp")

# Constants
API_BASE_URL = "https://api.example.com/v1"

# Enums
class ResponseFormat(str, Enum):
    '''Output format for tool responses.'''
    MARKDOWN = "markdown"
    JSON = "json"

# Pydantic Models for Input Validation
class UserSearchInput(BaseModel):
    '''Input model for user search operations.'''
    model_config = ConfigDict(
        str_strip_whitespace=True,
        validate_assignment=True
    )

    query: str = Field(..., description="Search string to match against names/emails", min_length=2, max_length=200)
    limit: Optional[int] = Field(default=20, description="Maximum results to return", ge=1, le=100)
    offset: Optional[int] = Field(default=0, description="Number of results to skip for pagination", ge=0)
    response_format: ResponseFormat = Field(default=ResponseFormat.MARKDOWN, description="Output format")

    @field_validator('query')
    @classmethod
    def validate_query(cls, v: str) -> str:
        if not v.strip():
            raise ValueError("Query cannot be empty or whitespace only")
        return v.strip()

# Shared utility functions
async def _make_api_request(endpoint: str, method: str = "GET", **kwargs) -> dict:
    '''Reusable function for all API calls.'''
    async with httpx.AsyncClient() as client:
        response = await client.request(
            method,
            f"{API_BASE_URL}/{endpoint}",
            timeout=30.0,
            **kwargs
        )
        response.raise_for_status()
        return response.json()

def _handle_api_error(e: Exception) -> str:
    '''Consistent error formatting across all tools.'''
    if isinstance(e, httpx.HTTPStatusError):
        if e.response.status_code == 404:
            return "Error: Resource not found. Please check the ID is correct."
        elif e.response.status_code == 403:
            return "Error: Permission denied. You don't have access to this resource."
        elif e.response.status_code == 429:
            return "Error: Rate limit exceeded. Please wait before making more requests."
        return f"Error: API request failed with status {e.response.status_code}"
    elif isinstance(e, httpx.TimeoutException):
        return "Error: Request timed out. Please try again."
    return f"Error: Unexpected error occurred: {type(e).__name__}"

# Tool definitions
@mcp.tool(
    name="example_search_users",
    annotations={
        "title": "Search Example Users",
        "readOnlyHint": True,
        "destructiveHint": False,
        "idempotentHint": True,
        "openWorldHint": True
    }
)
async def example_search_users(params: UserSearchInput) -> str:
    '''Search for users in the Example system by name, email, or team.

    [Full docstring as shown above]
    '''
    try:
        # Make API request using validated parameters
        data = await _make_api_request(
            "users/search",
            params={
                "q": params.query,
                "limit": params.limit,
                "offset": params.offset
            }
        )

        users = data.get("users", [])
        total = data.get("total", 0)

        if not users:
            return f"No users found matching '{params.query}'"

        # Format response based on requested format
        if params.response_format == ResponseFormat.MARKDOWN:
            lines = [f"# User Search Results: '{params.query}'", ""]
            lines.append(f"Found {total} users (showing {len(users)})")
            lines.append("")

            for user in users:
                lines.append(f"## {user['name']} ({user['id']})")
                lines.append(f"- **Email**: {user['email']}")
                if user.get('team'):
                    lines.append(f"- **Team**: {user['team']}")
                lines.append("")

            return "\n".join(lines)

        else:
            # Machine-readable JSON format
            import json
            response = {
                "total": total,
                "count": len(users),
                "offset": params.offset,
                "users": users
            }
            return json.dumps(response, indent=2)

    except Exception as e:
        return _handle_api_error(e)

if __name__ == "__main__":
    mcp.run()
```

---

## Các Tính Năng Nâng Cao Của FastMCP

### Tiêm Tham Số Ngữ Cảnh (Context Parameter Injection)

FastMCP có thể tự động tiêm (inject) một tham số `Context` vào các công cụ để cung cấp những năng lực nâng cao như ghi nhật ký (logging), báo cáo tiến độ, đọc tài nguyên và tương tác với người dùng:

```python
from mcp.server.fastmcp import FastMCP, Context

mcp = FastMCP("example_mcp")

@mcp.tool()
async def advanced_search(query: str, ctx: Context) -> str:
    '''Advanced tool with context access for logging and progress.'''

    # Report progress for long operations
    await ctx.report_progress(0.25, "Starting search...")

    # Log information for debugging
    await ctx.log_info("Processing query", {"query": query, "timestamp": datetime.now()})

    # Perform search
    results = await search_api(query)
    await ctx.report_progress(0.75, "Formatting results...")

    # Access server configuration
    server_name = ctx.fastmcp.name

    return format_results(results)

@mcp.tool()
async def interactive_tool(resource_id: str, ctx: Context) -> str:
    '''Tool that can request additional input from users.'''

    # Request sensitive information when needed
    api_key = await ctx.elicit(
        prompt="Please provide your API key:",
        input_type="password"
    )

    # Use the provided key
    return await api_call(resource_id, api_key)
```

**Các năng lực của Context:**
- `ctx.report_progress(progress, message)` - Báo cáo tiến độ cho các tác vụ chạy lâu
- `ctx.log_info(message, data)` / `ctx.log_error()` / `ctx.log_debug()` - Ghi nhật ký
- `ctx.elicit(prompt, input_type)` - Yêu cầu nhập thông tin bổ sung từ người dùng
- `ctx.fastmcp.name` - Truy cập cấu hình máy chủ
- `ctx.read_resource(uri)` - Đọc tài nguyên MCP

### Đăng Ký Tài Nguyên (Resource Registration)

Phơi bày dữ liệu dưới dạng tài nguyên để truy cập hiệu quả dựa trên khuôn mẫu (template-based):

```python
@mcp.resource("file://documents/{name}")
async def get_document(name: str) -> str:
    '''Expose documents as MCP resources.

    Resources are useful for static or semi-static data that doesn't
    require complex parameters. They use URI templates for flexible access.
    '''
    document_path = f"./docs/{name}"
    with open(document_path, "r") as f:
        return f.read()

@mcp.resource("config://settings/{key}")
async def get_setting(key: str, ctx: Context) -> str:
    '''Expose configuration as resources with context.'''
    settings = await load_settings()
    return json.dumps(settings.get(key, {}))
```

**Khi nào nên dùng Resources so với Tools:**
- **Resources**: Dành cho việc truy cập dữ liệu với các tham số đơn giản (khuôn mẫu URI)
- **Tools**: Dành cho các thao tác phức tạp đòi hỏi xác thực dữ liệu và xử lý logic nghiệp vụ

### Kiểu Đầu Ra Có Cấu Trúc (Structured Output Types)

FastMCP hỗ trợ nhiều kiểu dữ liệu trả về ngoài chuỗi ký tự (strings) thông thường:

```python
from typing import TypedDict
from dataclasses import dataclass
from pydantic import BaseModel

# TypedDict for structured returns
class UserData(TypedDict):
    id: str
    name: str
    email: str

@mcp.tool()
async def get_user_typed(user_id: str) -> UserData:
    '''Returns structured data - FastMCP handles serialization.'''
    return {"id": user_id, "name": "John Doe", "email": "john@example.com"}

# Pydantic models for complex validation
class DetailedUser(BaseModel):
    id: str
    name: str
    email: str
    created_at: datetime
    metadata: Dict[str, Any]

@mcp.tool()
async def get_user_detailed(user_id: str) -> DetailedUser:
    '''Returns Pydantic model - automatically generates schema.'''
    user = await fetch_user(user_id)
    return DetailedUser(**user)
```

### Quản Lý Vòng Đời (Lifespan Management)

Khởi tạo các tài nguyên duy trì xuyên suốt qua nhiều yêu cầu (requests):

```python
from contextlib import asynccontextmanager

@asynccontextmanager
async def app_lifespan():
    '''Manage resources that live for the server's lifetime.'''
    # Initialize connections, load config, etc.
    db = await connect_to_database()
    config = load_configuration()

    # Make available to all tools
    yield {"db": db, "config": config}

    # Cleanup on shutdown
    await db.close()

mcp = FastMCP("example_mcp", lifespan=app_lifespan)

@mcp.tool()
async def query_data(query: str, ctx: Context) -> str:
    '''Access lifespan resources through context.'''
    db = ctx.request_context.lifespan_state["db"]
    results = await db.query(query)
    return format_results(results)
```

### Các Tùy Chọn Truyền Tải (Transport Options)

FastMCP hỗ trợ hai cơ chế truyền tải chính:

```python
# stdio transport (for local tools) - default
if __name__ == "__main__":
    mcp.run()

# Streamable HTTP transport (for remote servers)
if __name__ == "__main__":
    mcp.run(transport="streamable_http", port=8000)
```

**Lựa chọn phương thức truyền tải:**
- **stdio**: Công cụ dòng lệnh, tích hợp cục bộ, thực thi dưới dạng tiến trình con (subprocess)
- **Streamable HTTP**: Dịch vụ web, truy cập từ xa, phục vụ nhiều ứng dụng khách (clients) cùng lúc

---

## Các Thông Lệ Tốt Nhất Về Mã Nguồn

### Khả Năng Kết Hợp Và Tái Sử Dụng Mã Nguồn (Code Composability and Reusability)

Bản triển khai của bạn BẮT BUỘC phải ưu tiên tính kết hợp và khả năng tái sử dụng mã nguồn:

1. **Tách Các Chức Năng Chung**:
   - Tạo các hàm bổ trợ (helper functions) tái sử dụng được cho những thao tác xuất hiện ở nhiều công cụ
   - Xây dựng các API client dùng chung cho các yêu cầu HTTP thay vì viết lặp lại mã nguồn
   - Tập trung hóa logic xử lý lỗi vào các hàm tiện ích
   - Tách logic nghiệp vụ vào các hàm chuyên biệt có thể kết hợp lại với nhau
   - Tách riêng chức năng chọn lọc trường dữ liệu & định dạng kết quả Markdown hoặc JSON dùng chung

2. **Tránh Trùng Lặp Mã Nguồn**:
   - KHÔNG BAO GIỜ sao chép-dán (copy-paste) các đoạn mã tương tự nhau giữa các công cụ
   - Nếu bạn thấy mình đang viết một logic tương tự đến lần thứ hai, hãy tách nó thành một hàm dùng chung
   - Các thao tác phổ biến như phân trang, lọc dữ liệu, chọn trường và định dạng kết quả cần được chia sẻ chung
   - Logic xác thực và phân quyền cần được tập trung hóa ở một nơi

### Các Thông Lệ Tốt Nhất Dành Riêng Cho Python

1. **Sử dụng Type Hints**: Luôn khai báo chú thích kiểu dữ liệu cho tham số hàm và giá trị trả về
2. **Mô hình Pydantic**: Định nghĩa các mô hình Pydantic rõ ràng cho mọi bước xác thực đầu vào
3. **Tránh Xác thực Thủ công**: Hãy để Pydantic xử lý việc xác thực đầu vào kèm theo các ràng buộc (constraints)
4. **Sắp xếp Lệnh Import Chuẩn xác**: Gom nhóm các lệnh import theo thứ tự (thư viện chuẩn, thư viện bên thứ ba, thư viện nội bộ)
5. **Xử lý Lỗi Cụ thể**: Sử dụng các kiểu ngoại lệ cụ thể (`httpx.HTTPStatusError`, không bắt `Exception` chung chung)
6. **Trình Quản lý Ngữ cảnh Bất đồng bộ (Async Context Managers)**: Sử dụng `async with` cho các tài nguyên cần giải phóng sau khi dùng
7. **Hằng số (Constants)**: Định nghĩa các hằng số cấp mô-đun bằng chữ IN HOA (`UPPER_CASE`)

## Danh Sách Kiểm Tra Chất Lượng (Quality Checklist)

Trước khi hoàn tất việc triển khai máy chủ MCP bằng Python, hãy đảm bảo:

### Thiết Kế Chiến Lược (Strategic Design)
- [ ] Các công cụ hỗ trợ thực hiện các luồng công việc hoàn chỉnh, chứ không chỉ là lớp vỏ bọc mỏng quanh các điểm cuối API
- [ ] Tên công cụ phản ánh sự phân chia tác vụ một cách tự nhiên
- [ ] Định dạng phản hồi được tối ưu hóa để tiết kiệm ngữ cảnh (context efficiency) cho tác tử
- [ ] Sử dụng các mã định danh dễ đọc cho con người ở những chỗ phù hợp
- [ ] Thông báo lỗi hướng dẫn tác tử đi tới cách sử dụng đúng

### Chất Lượng Triển Khai (Implementation Quality)
- [ ] TRIỂN KHAI CÓ TRỌNG TÂM: Đã triển khai các công cụ quan trọng và mang lại nhiều giá trị nhất
- [ ] Tất cả công cụ đều có tên gọi giàu tính mô tả và tài liệu hướng dẫn đầy đủ
- [ ] Kiểu dữ liệu trả về nhất quán giữa các thao tác tương tự nhau
- [ ] Đã triển khai xử lý lỗi cho toàn bộ các lệnh gọi ra dịch vụ bên ngoài
- [ ] Tên máy chủ tuân thủ đúng định dạng: `{service}_mcp`
- [ ] Mọi thao tác mạng đều sử dụng `async/await`
- [ ] Các chức năng chung được tách thành các hàm tái sử dụng
- [ ] Các thông báo lỗi rõ ràng, có tính hành động và mang tính hướng dẫn cao
- [ ] Đầu ra được xác thực và định dạng chuẩn xác

### Cấu Hình Công Cụ (Tool Configuration)
- [ ] Tất cả công cụ đều khai báo `'name'` và `'annotations'` trong decorator
- [ ] Các chú thích (`annotations`) được thiết lập chính xác (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`)
- [ ] Tất cả công cụ đều sử dụng `BaseModel` của Pydantic để xác thực đầu vào kèm theo định nghĩa `Field()`
- [ ] Tất cả các trường `Field` của Pydantic đều có kiểu dữ liệu tường minh và mô tả kèm ràng buộc
- [ ] Tất cả công cụ đều có docstring toàn diện với kiểu đầu vào/đầu ra tường minh
- [ ] Docstring bao gồm cấu trúc lược đồ hoàn chỉnh cho các giá trị trả về dạng dict/JSON
- [ ] Các mô hình Pydantic đảm nhiệm việc xác thực đầu vào (không cần viết mã kiểm tra thủ công)

### Các Tính Năng Nâng Cao (nếu áp dụng)
- [ ] Sử dụng tiêm ngữ cảnh (Context injection) cho việc ghi log, báo cáo tiến độ hoặc hỏi thêm thông tin người dùng
- [ ] Đã đăng ký Resources cho các điểm cuối dữ liệu phù hợp
- [ ] Đã triển khai quản lý vòng đời (Lifespan management) cho các kết nối duy trì liên tục
- [ ] Sử dụng các kiểu đầu ra có cấu trúc (`TypedDict`, mô hình Pydantic)
- [ ] Đã cấu hình cơ chế truyền tải phù hợp (`stdio` hoặc `streamable HTTP`)

### Chất Lượng Mã Nguồn (Code Quality)
- [ ] Tệp mã nguồn bao gồm đầy đủ các lệnh import hợp lệ, trong đó có các import từ Pydantic
- [ ] Cơ chế phân trang được triển khai đúng cách ở những nơi cần thiết
- [ ] Cung cấp các tùy chọn lọc (filtering) cho các tập kết quả có khả năng phình to
- [ ] Tất cả các hàm bất đồng bộ đều được định nghĩa đúng bằng `async def`
- [ ] Việc sử dụng HTTP client tuân theo mẫu bất đồng bộ với trình quản lý ngữ cảnh (`async with`) chuẩn xác
- [ ] Gợi ý kiểu dữ liệu (Type hints) được sử dụng xuyên suốt toàn bộ mã nguồn
- [ ] Các hằng số được định nghĩa ở cấp mô-đun bằng chữ IN HOA (`UPPER_CASE`)

### Kiểm Thử (Testing)
- [ ] Máy chủ chạy thành công với lệnh: `python your_server.py --help`
- [ ] Tất cả các lệnh import đều phân giải đường dẫn chính xác
- [ ] Các lệnh gọi công cụ mẫu hoạt động đúng như kỳ vọng
- [ ] Các kịch bản lỗi được xử lý êm thấm, không làm sập máy chủ
FILE:scripts/connections.py
"""Lightweight connection handling for MCP servers."""

from abc import ABC, abstractmethod
from contextlib import AsyncExitStack
from typing import Any

from mcp import ClientSession, StdioServerParameters
from mcp.client.sse import sse_client
from mcp.client.stdio import stdio_client
from mcp.client.streamable_http import streamablehttp_client


class MCPConnection(ABC):
    """Base class for MCP server connections."""

    def __init__(self):
        self.session = None
        self._stack = None

    @abstractmethod
    def _create_context(self):
        """Create the connection context based on connection type."""

    async def __aenter__(self):
        """Initialize MCP server connection."""
        self._stack = AsyncExitStack()
        await self._stack.__aenter__()

        try:
            ctx = self._create_context()
            result = await self._stack.enter_async_context(ctx)

            if len(result) == 2:
                read, write = result
            elif len(result) == 3:
                read, write, _ = result
            else:
                raise ValueError(f"Unexpected context result: {result}")

            session_ctx = ClientSession(read, write)
            self.session = await self._stack.enter_async_context(session_ctx)
            await self.session.initialize()
            return self
        except BaseException:
            await self._stack.__aexit__(None, None, None)
            raise

    async def __aexit__(self, exc_type, exc_val, exc_tb):
        """Clean up MCP server connection resources."""
        if self._stack:
            await self._stack.__aexit__(exc_type, exc_val, exc_tb)
        self.session = None
        self._stack = None

    async def list_tools(self) -> list[dict[str, Any]]:
        """Retrieve available tools from the MCP server."""
        response = await self.session.list_tools()
        return [
            {
                "name": tool.name,
                "description": tool.description,
                "input_schema": tool.inputSchema,
            }
            for tool in response.tools
        ]

    async def call_tool(self, tool_name: str, arguments: dict[str, Any]) -> Any:
        """Call a tool on the MCP server with provided arguments."""
        result = await self.session.call_tool(tool_name, arguments=arguments)
        return result.content


class MCPConnectionStdio(MCPConnection):
    """MCP connection using standard input/output."""

    def __init__(self, command: str, args: list[str] = None, env: dict[str, str] = None):
        super().__init__()
        self.command = command
        self.args = args or []
        self.env = env

    def _create_context(self):
        return stdio_client(
            StdioServerParameters(command=self.command, args=self.args, env=self.env)
        )


class MCPConnectionSSE(MCPConnection):
    """MCP connection using Server-Sent Events."""

    def __init__(self, url: str, headers: dict[str, str] = None):
        super().__init__()
        self.url = url
        self.headers = headers or {}

    def _create_context(self):
        return sse_client(url=self.url, headers=self.headers)


class MCPConnectionHTTP(MCPConnection):
    """MCP connection using Streamable HTTP."""

    def __init__(self, url: str, headers: dict[str, str] = None):
        super().__init__()
        self.url = url
        self.headers = headers or {}

    def _create_context(self):
        return streamablehttp_client(url=self.url, headers=self.headers)


def create_connection(
    transport: str,
    command: str = None,
    args: list[str] = None,
    env: dict[str, str] = None,
    url: str = None,
    headers: dict[str, str] = None,
) -> MCPConnection:
    """Factory function to create the appropriate MCP connection.

    Args:
        transport: Connection type ("stdio", "sse", or "http")
        command: Command to run (stdio only)
        args: Command arguments (stdio only)
        env: Environment variables (stdio only)
        url: Server URL (sse and http only)
        headers: HTTP headers (sse and http only)

    Returns:
        MCPConnection instance
    """
    transport = transport.lower()

    if transport == "stdio":
        if not command:
            raise ValueError("Command is required for stdio transport")
        return MCPConnectionStdio(command=command, args=args, env=env)

    elif transport == "sse":
        if not url:
            raise ValueError("URL is required for sse transport")
        return MCPConnectionSSE(url=url, headers=headers)

    elif transport in ["http", "streamable_http", "streamable-http"]:
        if not url:
            raise ValueError("URL is required for http transport")
        return MCPConnectionHTTP(url=url, headers=headers)

    else:
        raise ValueError(f"Unsupported transport type: {transport}. Use 'stdio', 'sse', or 'http'")
FILE:scripts/evaluation.py
"""MCP Server Evaluation Harness

This script evaluates MCP servers by running test questions against them using Claude.
"""

import argparse
import asyncio
import json
import re
import sys
import time
import traceback
import xml.etree.ElementTree as ET
from pathlib import Path
from typing import Any

from anthropic import Anthropic

from connections import create_connection

EVALUATION_PROMPT = """You are an AI assistant with access to tools.

When given a task, you MUST:
1. Use the available tools to complete the task
2. Provide summary of each step in your approach, wrapped in <summary> tags
3. Provide feedback on the tools provided, wrapped in <feedback> tags
4. Provide your final response, wrapped in <response> tags

Summary Requirements:
- In your <summary> tags, you must explain:
  - The steps you took to complete the task
  - Which tools you used, in what order, and why
  - The inputs you provided to each tool
  - The outputs you received from each tool
  - A summary for how you arrived at the response

Feedback Requirements:
- In your <feedback> tags, provide constructive feedback on the tools:
  - Comment on tool names: Are they clear and descriptive?
  - Comment on input parameters: Are they well-documented? Are required vs optional parameters clear?
  - Comment on descriptions: Do they accurately describe what the tool does?
  - Comment on any errors encountered during tool usage: Did the tool fail to execute? Did the tool return too many tokens?
  - Identify specific areas for improvement and explain WHY they would help
  - Be specific and actionable in your suggestions

Response Requirements:
- Your response should be concise and directly address what was asked
- Always wrap your final response in <response> tags
- If you cannot solve the task return <response>NOT_FOUND</response>
- For numeric responses, provide just the number
- For IDs, provide just the ID
- For names or text, provide the exact text requested
- Your response should go last"""


def parse_evaluation_file(file_path: Path) -> list[dict[str, Any]]:
    """Parse XML evaluation file with qa_pair elements."""
    try:
        tree = ET.parse(file_path)
        root = tree.getroot()
        evaluations = []

        for qa_pair in root.findall(".//qa_pair"):
            question_elem = qa_pair.find("question")
            answer_elem = qa_pair.find("answer")

            if question_elem is not None and answer_elem is not None:
                evaluations.append({
                    "question": (question_elem.text or "").strip(),
                    "answer": (answer_elem.text or "").strip(),
                })

        return evaluations
    except Exception as e:
        print(f"Error parsing evaluation file {file_path}: {e}")
        return []


def extract_xml_content(text: str, tag: str) -> str | None:
    """Extract content from XML tags."""
    pattern = rf"<{tag}>(.*?)</{tag}>"
    matches = re.findall(pattern, text, re.DOTALL)
    return matches[-1].strip() if matches else None


async def agent_loop(
    client: Anthropic,
    model: str,
    question: str,
    tools: list[dict[str, Any]],
    connection: Any,
) -> tuple[str, dict[str, Any]]:
    """Run the agent loop with MCP tools."""
    messages = [{"role": "user", "content": question}]

    response = await asyncio.to_thread(
        client.messages.create,
        model=model,
        max_tokens=4096,
        system=EVALUATION_PROMPT,
        messages=messages,
        tools=tools,
    )

    messages.append({"role": "assistant", "content": response.content})

    tool_metrics = {}

    while response.stop_reason == "tool_use":
        tool_use = next(block for block in response.content if block.type == "tool_use")
        tool_name = tool_use.name
        tool_input = tool_use.input

        tool_start_ts = time.time()
        try:
            tool_result = await connection.call_tool(tool_name, tool_input)
            tool_response = json.dumps(tool_result) if isinstance(tool_result, (dict, list)) else str(tool_result)
        except Exception as e:
            tool_response = f"Error executing tool {tool_name}: {str(e)}\n"
            tool_response += traceback.format_exc()
        tool_duration = time.time() - tool_start_ts

        if tool_name not in tool_metrics:
            tool_metrics[tool_name] = {"count": 0, "durations": []}
        tool_metrics[tool_name]["count"] += 1
        tool_metrics[tool_name]["durations"].append(tool_duration)

        messages.append({
            "role": "user",
            "content": [{
                "type": "tool_result",
                "tool_use_id": tool_use.id,
                "content": tool_response,
            }]
        })

        response = await asyncio.to_thread(
            client.messages.create,
            model=model,
            max_tokens=4096,
            system=EVALUATION_PROMPT,
            messages=messages,
            tools=tools,
        )
        messages.append({"role": "assistant", "content": response.content})

    response_text = next(
        (block.text for block in response.content if hasattr(block, "text")),
        None,
    )
    return response_text, tool_metrics


async def evaluate_single_task(
    client: Anthropic,
    model: str,
    qa_pair: dict[str, Any],
    tools: list[dict[str, Any]],
    connection: Any,
    task_index: int,
) -> dict[str, Any]:
    """Evaluate a single QA pair with the given tools."""
    start_time = time.time()

    print(f"Task {task_index + 1}: Running task with question: {qa_pair['question']}")
    response, tool_metrics = await agent_loop(client, model, qa_pair["question"], tools, connection)

    response_value = extract_xml_content(response, "response")
    summary = extract_xml_content(response, "summary")
    feedback = extract_xml_content(response, "feedback")

    duration_seconds = time.time() - start_time

    return {
        "question": qa_pair["question"],
        "expected": qa_pair["answer"],
        "actual": response_value,
        "score": int(response_value == qa_pair["answer"]) if response_value else 0,
        "total_duration": duration_seconds,
        "tool_calls": tool_metrics,
        "num_tool_calls": sum(len(metrics["durations"]) for metrics in tool_metrics.values()),
        "summary": summary,
        "feedback": feedback,
    }


REPORT_HEADER = """
# Evaluation Report

## Summary

- **Accuracy**: {correct}/{total} ({accuracy:.1f}%)
- **Average Task Duration**: {average_duration_s:.2f}s
- **Average Tool Calls per Task**: {average_tool_calls:.2f}
- **Total Tool Calls**: {total_tool_calls}

---
"""

TASK_TEMPLATE = """
### Task {task_num}

**Question**: {question}
**Ground Truth Answer**: `{expected_answer}`
**Actual Answer**: `{actual_answer}`
**Correct**: {correct_indicator}
**Duration**: {total_duration:.2f}s
**Tool Calls**: {tool_calls}

**Summary**
{summary}

**Feedback**
{feedback}

---
"""


async def run_evaluation(
    eval_path: Path,
    connection: Any,
    model: str = "claude-3-7-sonnet-20250219",
) -> str:
    """Run evaluation with MCP server tools."""
    print("🚀 Starting Evaluation")

    client = Anthropic()

    tools = await connection.list_tools()
    print(f"📋 Loaded {len(tools)} tools from MCP server")

    qa_pairs = parse_evaluation_file(eval_path)
    print(f"📋 Loaded {len(qa_pairs)} evaluation tasks")

    results = []
    for i, qa_pair in enumerate(qa_pairs):
        print(f"Processing task {i + 1}/{len(qa_pairs)}")
        result = await evaluate_single_task(client, model, qa_pair, tools, connection, i)
        results.append(result)

    correct = sum(r["score"] for r in results)
    accuracy = (correct / len(results)) * 100 if results else 0
    average_duration_s = sum(r["total_duration"] for r in results) / len(results) if results else 0
    average_tool_calls = sum(r["num_tool_calls"] for r in results) / len(results) if results else 0
    total_tool_calls = sum(r["num_tool_calls"] for r in results)

    report = REPORT_HEADER.format(
        correct=correct,
        total=len(results),
        accuracy=accuracy,
        average_duration_s=average_duration_s,
        average_tool_calls=average_tool_calls,
        total_tool_calls=total_tool_calls,
    )

    report += "".join([
        TASK_TEMPLATE.format(
            task_num=i + 1,
            question=qa_pair["question"],
            expected_answer=qa_pair["answer"],
            actual_answer=result["actual"] or "N/A",
            correct_indicator="✅" if result["score"] else "❌",
            total_duration=result["total_duration"],
            tool_calls=json.dumps(result["tool_calls"], indent=2),
            summary=result["summary"] or "N/A",
            feedback=result["feedback"] or "N/A",
        )
        for i, (qa_pair, result) in enumerate(zip(qa_pairs, results))
    ])

    return report


def parse_headers(header_list: list[str]) -> dict[str, str]:
    """Parse header strings in format 'Key: Value' into a dictionary."""
    headers = {}
    if not header_list:
        return headers

    for header in header_list:
        if ":" in header:
            key, value = header.split(":", 1)
            headers[key.strip()] = value.strip()
        else:
            print(f"Warning: Ignoring malformed header: {header}")
    return headers


def parse_env_vars(env_list: list[str]) -> dict[str, str]:
    """Parse environment variable strings in format 'KEY=VALUE' into a dictionary."""
    env = {}
    if not env_list:
        return env

    for env_var in env_list:
        if "=" in env_var:
            key, value = env_var.split("=", 1)
            env[key.strip()] = value.strip()
        else:
            print(f"Warning: Ignoring malformed environment variable: {env_var}")
    return env


async def main():
    parser = argparse.ArgumentParser(
        description="Evaluate MCP servers using test questions",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  # Evaluate a local stdio MCP server
  python evaluation.py -t stdio -c python -a my_server.py eval.xml

  # Evaluate an SSE MCP server
  python evaluation.py -t sse -u https://example.com/mcp -H "Authorization: Bearer token" eval.xml

  # Evaluate an HTTP MCP server with custom model
  python evaluation.py -t http -u https://example.com/mcp -m claude-3-5-sonnet-20241022 eval.xml
        """,
    )

    parser.add_argument("eval_file", type=Path, help="Path to evaluation XML file")
    parser.add_argument("-t", "--transport", choices=["stdio", "sse", "http"], default="stdio", help="Transport type (default: stdio)")
    parser.add_argument("-m", "--model", default="claude-3-7-sonnet-20250219", help="Claude model to use (default: claude-3-7-sonnet-20250219)")

    stdio_group = parser.add_argument_group("stdio options")
    stdio_group.add_argument("-c", "--command", help="Command to run MCP server (stdio only)")
    stdio_group.add_argument("-a", "--args", nargs="+", help="Arguments for the command (stdio only)")
    stdio_group.add_argument("-e", "--env", nargs="+", help="Environment variables in KEY=VALUE format (stdio only)")

    remote_group = parser.add_argument_group("sse/http options")
    remote_group.add_argument("-u", "--url", help="MCP server URL (sse/http only)")
    remote_group.add_argument("-H", "--header", nargs="+", dest="headers", help="HTTP headers in 'Key: Value' format (sse/http only)")

    parser.add_argument("-o", "--output", type=Path, help="Output file for evaluation report (default: stdout)")

    args = parser.parse_args()

    if not args.eval_file.exists():
        print(f"Error: Evaluation file not found: {args.eval_file}")
        sys.exit(1)

    headers = parse_headers(args.headers) if args.headers else None
    env_vars = parse_env_vars(args.env) if args.env else None

    try:
        connection = create_connection(
            transport=args.transport,
            command=args.command,
            args=args.args,
            env=env_vars,
            url=args.url,
            headers=headers,
        )
    except ValueError as e:
        print(f"Error: {e}")
        sys.exit(1)

    print(f"🔗 Connecting to MCP server via {args.transport}...")

    async with connection:
        print("✅ Connected successfully")
        report = await run_evaluation(args.eval_file, connection, args.model)

        if args.output:
            args.output.write_text(report)
            print(f"\n✅ Report saved to {args.output}")
        else:
            print("\n" + report)


if __name__ == "__main__":
    asyncio.run(main())
FILE:scripts/example_evaluation.xml
<evaluation>
   <qa_pair>
      <question>Calculate the compound interest on $10,000 invested at 5% annual interest rate, compounded monthly for 3 years. What is the final amount in dollars (rounded to 2 decimal places)?</question>
      <answer>11614.72</answer>
   </qa_pair>
   <qa_pair>
      <question>A projectile is launched at a 45-degree angle with an initial velocity of 50 m/s. Calculate the total distance (in meters) it has traveled from the launch point after 2 seconds, assuming g=9.8 m/s². Round to 2 decimal places.</question>
      <answer>87.25</answer>
   </qa_pair>
   <qa_pair>
      <question>A sphere has a volume of 500 cubic meters. Calculate its surface area in square meters. Round to 2 decimal places.</question>
      <answer>304.65</answer>
   </qa_pair>
   <qa_pair>
      <question>Calculate the population standard deviation of this dataset: [12, 15, 18, 22, 25, 30, 35]. Round to 2 decimal places.</question>
      <answer>7.61</answer>
   </qa_pair>
   <qa_pair>
      <question>Calculate the pH of a solution with a hydrogen ion concentration of 3.5 × 10^-5 M. Round to 2 decimal places.</question>
      <answer>4.46</answer>
   </qa_pair>
</evaluation>
FILE:scripts/requirements.txt
anthropic>=0.39.0
mcp>=1.1.0

API Python TypeScript+2

F@f

Trình Tạo Kỹ Năng (Skill Creator)

Kỹ năng

Hướng dẫn tạo các kỹ năng (skills) hiệu quả. Kỹ năng này nên được sử dụng khi người dùng muốn tạo một kỹ năng mới (hoặc cập nhật một kỹ năng hiện có) giúp mở rộng khả năng của Claude bằng kiến thức chuyên ngành, quy trình làm việc hoặc tích hợp công cụ.

---
name: skill-creator
description: Hướng dẫn tạo các kỹ năng (skills) hiệu quả. Kỹ năng này nên được sử dụng khi người dùng muốn tạo một kỹ năng mới (hoặc cập nhật một kỹ năng hiện có) giúp mở rộng khả năng của Claude bằng kiến thức chuyên ngành, quy trình làm việc hoặc tích hợp công cụ.
license: Xem đầy đủ các điều khoản trong LICENSE.txt
---

# Trình Tạo Kỹ Năng (Skill Creator)

Kỹ năng này cung cấp hướng dẫn để tạo ra các kỹ năng (skills) hiệu quả.

## Giới Thiệu Về Kỹ Năng (Skills)

Kỹ năng (Skills) là các gói mô-đun độc lập, khép kín giúp mở rộng khả năng của Claude bằng cách cung cấp
kiến thức chuyên ngành, quy trình làm việc và các công cụ chuyên biệt. Hãy hình dung chúng như những "cẩm nang hội nhập" (onboarding guides) cho các lĩnh vực
hoặc tác vụ cụ thể—chúng biến đổi Claude từ một tác tử đa năng thành một tác tử chuyên gia
được trang bị tri thức quy trình mà không một mô hình đơn lẻ nào có thể tự nắm giữ trọn vẹn.

### Những Gì Kỹ Năng Cung Cấp

1. Quy trình làm việc chuyên biệt - Các thủ tục nhiều bước dành cho những lĩnh vực cụ thể
2. Tích hợp công cụ - Hướng dẫn làm việc với các định dạng tệp hoặc API cụ thể
3. Chuyên môn nghiệp vụ - Kiến thức đặc thù của công ty, lược đồ dữ liệu (schemas), logic nghiệp vụ
4. Tài nguyên đóng gói kèm - Các kịch bản (scripts), tài liệu tham khảo (references) và tài sản (assets) phục vụ các tác vụ phức tạp và lặp đi lặp lại

## Các Nguyên Tắc Cốt Lõi

### Ngắn Gọn Là Chìa Khóa

Cửa sổ ngữ cảnh (context window) là tài sản chung. Các kỹ năng phải chia sẻ cửa sổ ngữ cảnh với mọi thứ khác mà Claude cần: câu lệnh hệ thống (system prompt), lịch sử hội thoại, siêu dữ liệu của các Kỹ năng khác và yêu cầu thực tế của người dùng.

**Giả định mặc định: Bản thân Claude vốn đã rất thông minh.** Chỉ bổ sung những ngữ cảnh mà Claude chưa có sẵn. Hãy chất vấn từng mẩu thông tin: "Claude có thực sự cần lời giải thích này không?" và "Đoạn văn này có xứng đáng với chi phí token mà nó tiêu tốn không?"

Ưu tiên các ví dụ ngắn gọn hơn là những lời giải thích dài dòng.

### Thiết Lập Bậc Tự Do Phù Hợp

Điều chỉnh mức độ chi tiết tương ứng với độ nhạy cảm dễ lỗi và tính biến thiên của tác vụ:

**Bậc tự do cao (hướng dẫn dạng văn bản)**: Sử dụng khi có nhiều cách tiếp cận cùng hợp lệ, các quyết định phụ thuộc vào ngữ cảnh, hoặc các nguyên tắc kinh nghiệm (heuristics) đóng vai trò dẫn dắt.

**Bậc tự do trung bình (mã giả hoặc kịch bản có tham số)**: Sử dụng khi đã có một mẫu chuẩn được ưu tiên, chấp nhận một số biến thể nhất định, hoặc cấu hình có ảnh hưởng đến hành vi.

**Bậc tự do thấp (các kịch bản cụ thể, ít tham số)**: Sử dụng khi các thao tác rất nhạy cảm và dễ phát sinh lỗi, tính nhất quán là yếu tố sống còn, hoặc bắt buộc phải tuân thủ nghiêm ngặt một trình tự cụ thể.

Hãy hình dung Claude đang khám phá một con đường: một cây cầu hẹp bắc qua vực thẳm cần những thanh lan can bảo vệ cụ thể (bậc tự do thấp), trong khi một cánh đồng rộng mở cho phép đi theo nhiều lối khác nhau (bậc tự do cao).

### Cấu Trúc Giải Phẫu Của Một Kỹ Năng

Mỗi kỹ năng bao gồm một tệp SKILL.md bắt buộc và các tài nguyên đóng gói kèm tùy chọn:

```
skill-name/
├── SKILL.md (bắt buộc)
│   ├── Siêu dữ liệu YAML frontmatter (bắt buộc)
│   │   ├── name: (bắt buộc)
│   │   └── description: (bắt buộc)
│   └── Hướng dẫn Markdown (bắt buộc)
└── Tài Nguyên Đóng Gói Kèm (tùy chọn)
    ├── scripts/          - Mã thực thi (Python/Bash/v.v.)
    ├── references/       - Tài liệu được nạp vào ngữ cảnh khi cần thiết
    └── assets/           - Các tệp được sử dụng trong kết quả đầu ra (mẫu, biểu tượng, phông chữ, v.v.)
```

#### SKILL.md (bắt buộc)

Mọi tệp SKILL.md đều bao gồm:

- **Frontmatter** (YAML): Chứa hai trường `name` và `description`. Đây là những trường duy nhất mà Claude đọc để xác định khi nào kỹ năng được kích hoạt sử dụng, do đó việc mô tả rõ ràng và toàn diện kỹ năng này là gì cũng như khi nào nên dùng nó là cực kỳ quan trọng.
- **Phần thân - Body** (Markdown): Các hướng dẫn và chỉ dẫn để sử dụng kỹ năng. Chỉ được nạp vào SAU KHI kỹ năng đã được kích hoạt (nếu có).

#### Tài Nguyên Đóng Gói Kèm (tùy chọn)

##### Kịch bản (`scripts/`)

Mã thực thi (Python/Bash/v.v.) dành cho các tác vụ đòi hỏi độ tin cậy tất định hoặc thường xuyên phải viết đi viết lại.

- **Khi nào nên đưa vào**: Khi cùng một đoạn mã cứ phải viết lại nhiều lần hoặc khi cần độ tin cậy tất định tuyệt đối
- **Ví dụ**: `scripts/rotate_pdf.py` cho các tác vụ xoay trang PDF
- **Lợi ích**: Tiết kiệm token, kết quả tất định, có thể được thực thi mà không cần nạp mã nguồn vào cửa sổ ngữ cảnh
- **Lưu ý**: Đôi khi Claude vẫn cần đọc các kịch bản này để vá lỗi hoặc điều chỉnh cho phù hợp với môi trường cụ thể

##### Tài liệu tham khảo (`references/`)

Tài liệu hướng dẫn và tư liệu tham khảo được thiết kế để nạp vào ngữ cảnh khi cần nhằm cung cấp thông tin cho quá trình xử lý và suy luận của Claude.

- **Khi nào nên đưa vào**: Dành cho các tài liệu mà Claude cần tra cứu trong quá trình làm việc
- **Ví dụ**: `references/finance.md` cho các lược đồ tài chính, `references/mnda.md` cho mẫu thỏa thuận bảo mật (NDA) của công ty, `references/policies.md` cho các chính sách công ty, `references/api_docs.md` cho đặc tả API
- **Trường hợp sử dụng**: Lược đồ cơ sở dữ liệu, tài liệu API, kiến thức chuyên ngành, chính sách công ty, hướng dẫn quy trình chi tiết
- **Lợi ích**: Giữ cho tệp SKILL.md luôn gọn nhẹ, chỉ nạp vào khi Claude xác định là thực sự cần dùng đến
- **Thực hành tốt nhất**: Nếu tệp có dung lượng lớn (>10k từ), hãy đưa các mẫu tìm kiếm grep vào trong SKILL.md
- **Tránh trùng lặp**: Thông tin chỉ nên nằm ở SKILL.md hoặc nằm ở các tệp trong thư mục references, không lặp lại ở cả hai nơi.

##### Tài sản (`assets/`)

Các tệp không nhằm mục đích nạp vào cửa sổ ngữ cảnh, mà được sử dụng trực tiếp bên trong sản phẩm đầu ra do Claude tạo ra.

- **Khi nào nên đưa vào**: Khi kỹ năng cần các tệp sẽ được đưa vào sản phẩm đầu ra cuối cùng
- **Ví dụ**: `assets/logo.png` cho tài sản nhận diện thương hiệu, `assets/slides.pptx` cho các mẫu bài thuyết trình PowerPoint
- **Trường hợp sử dụng**: Biểu mẫu (templates), hình ảnh, biểu tượng (icons), mã khung dựng sẵn (boilerplate code), phông chữ, tài liệu mẫu

### Nguyên Tắc Thiết Kế Tiết Lộ Dần Dần (Progressive Disclosure)

Các kỹ năng sử dụng hệ thống nạp ba cấp độ để quản lý ngữ cảnh một cách hiệu quả:

1. **Siêu dữ liệu (name + description)** - Luôn thường trực trong ngữ cảnh (~100 từ)
2. **Phần thân SKILL.md** - Được nạp khi kỹ năng được kích hoạt (<5k từ)
3. **Tài nguyên đóng gói kèm** - Được nạp theo nhu cầu thực tế của Claude

Hãy giữ phần thân SKILL.md tập trung vào những nội dung cốt lõi nhất và dưới 500 dòng để giảm thiểu tình trạng phình đại ngữ cảnh.

## Quy Trình Tạo Kỹ Năng

Việc tạo kỹ năng bao gồm các bước sau:

1. Hiểu rõ kỹ năng thông qua các ví dụ cụ thể
2. Lên kế hoạch cho các nội dung kỹ năng có thể tái sử dụng (scripts, references, assets)
3. Khởi tạo kỹ năng (chạy kịch bản init_skill.py)
4. Chỉnh sửa kỹ năng (triển khai các tài nguyên và viết nội dung SKILL.md)
5. Đóng gói kỹ năng (chạy kịch bản package_skill.py)
6. Lặp lại và cải tiến dựa trên quá trình sử dụng thực tế

### Bước 3: Khởi Tạo Kỹ Năng

Khi tạo một kỹ năng mới từ đầu, hãy luôn chạy kịch bản `init_skill.py`:

```bash
scripts/init_skill.py <skill-name> --path <output-directory>
```

### Bước 4: Chỉnh Sửa Kỹ Năng

Tham khảo các tài liệu hướng dẫn hữu ích sau dựa trên nhu cầu cụ thể của kỹ năng bạn đang tạo:

- **Các quy trình nhiều bước**: Xem references/workflows.md để biết các quy trình tuần tự và logic rẽ nhánh có điều kiện
- **Các định dạng đầu ra cụ thể hoặc tiêu chuẩn chất lượng**: Xem references/output-patterns.md để biết các mẫu biểu mẫu và mẫu ví dụ

### Bước 5: Đóng Gói Kỹ Năng

```bash
scripts/package_skill.py <path/to/skill-folder>
```

Kịch bản đóng gói sẽ kiểm tra tính hợp lệ và tạo ra một tệp .skill để phân phối.
FILE:references/workflows.md
# Các Mẫu Quy Trình Làm Việc (Workflow Patterns)

## Quy Trình Tuần Tự (Sequential Workflows)

Đối với các tác vụ phức tạp, hãy chia nhỏ hoạt động thành các bước tuần tự rõ ràng. Việc cung cấp cho Claude cái nhìn tổng quan về quy trình ngay ở phần đầu của tệp SKILL.md thường mang lại hiệu quả rất tốt:

```markdown
Việc điền một biểu mẫu PDF bao gồm các bước sau:

1. Phân tích biểu mẫu (chạy analyze_form.py)
2. Tạo ánh xạ trường dữ liệu (chỉnh sửa fields.json)
3. Xác thực ánh xạ (chạy validate_fields.py)
4. Điền biểu mẫu (chạy fill_form.py)
5. Kiểm tra kết quả đầu ra (chạy verify_output.py)
```

## Quy Trình Có Điều Kiện (Conditional Workflows)

Đối với các tác vụ có logic rẽ nhánh, hãy dẫn dắt Claude đi qua các điểm ra quyết định:

```markdown
1. Xác định loại sửa đổi:
   **Tạo nội dung mới?** → Làm theo "Quy trình tạo mới" bên dưới
   **Chỉnh sửa nội dung hiện có?** → Làm theo "Quy trình chỉnh sửa" bên dưới

2. Quy trình tạo mới: [steps]
3. Quy trình chỉnh sửa: [steps]
```
FILE:references/output-patterns.md
# Các Mẫu Đầu Ra (Output Patterns)

Sử dụng các mẫu này khi kỹ năng cần tạo ra kết quả đầu ra nhất quán, chất lượng cao.

## Mẫu Khuôn Khổ Định Sẵn (Template Pattern)

Cung cấp các biểu mẫu (templates) cho định dạng đầu ra. Điều chỉnh mức độ nghiêm ngặt sao cho khớp với nhu cầu của bạn.

**Đối với các yêu cầu nghiêm ngặt (như phản hồi API hoặc các định dạng dữ liệu cố định):**

```markdown
## Cấu trúc báo cáo

LUÔN LUÔN sử dụng chính xác cấu trúc biểu mẫu này:

# [Analysis Title]

## Tóm tắt điều hành (Executive summary)
[One-paragraph overview of key findings]

## Các phát hiện chính (Key findings)
- Phát hiện 1 kèm dữ liệu chứng minh
- Phát hiện 2 kèm dữ liệu chứng minh
- Phát hiện 3 kèm dữ liệu chứng minh

## Khuyến nghị (Recommendations)
1. Khuyến nghị cụ thể có tính hành động
2. Khuyến nghị cụ thể có tính hành động
```

**Đối với hướng dẫn linh hoạt (khi sự thích ứng theo tình huống mang lại lợi ích):**

```markdown
## Cấu trúc báo cáo

Dưới đây là định dạng mặc định hợp lý, nhưng hãy sử dụng sự phán đoán tốt nhất của bạn:

# [Analysis Title]

## Tóm tắt điều hành
[Overview]

## Các phát hiện chính
[Adapt sections based on what you discover]

## Khuyến nghị
[Tailor to the specific context]

Điều chỉnh các mục khi cần thiết cho phù hợp với loại hình phân tích cụ thể.
```

## Mẫu Ví Dự Minh Họa (Examples Pattern)

Đối với các kỹ năng mà chất lượng đầu ra phụ thuộc vào việc nhìn thấy các ví dụ mẫu, hãy cung cấp các cặp đầu vào/đầu ra (input/output pairs):

```markdown
## Định dạng thông điệp commit (Commit message format)

Tạo các thông điệp commit tuân theo các ví dụ sau:

**Ví dụ 1:**
Đầu vào (Input): Đã thêm xác thực người dùng bằng JWT tokens
Đầu ra (Output):
```
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware
```

**Ví dụ 2:**
Đầu vào (Input): Đã sửa lỗi ngày tháng hiển thị không chính xác trong các báo cáo
Đầu ra (Output):
```
fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation
```

Hãy tuân theo phong cách này: type(scope): mô tả ngắn gọn, sau đó là phần giải thích chi tiết.
```

Các ví dụ giúp Claude hiểu rõ phong cách mong muốn và mức độ chi tiết cụ thể hơn nhiều so với việc chỉ dùng lời mô tả đơn thuần.
FILE:scripts/quick_validate.py
#!/usr/bin/env python3
"""
Quick validation script for skills - minimal version
"""

import sys
import os
import re
import yaml
from pathlib import Path

def validate_skill(skill_path):
    """Basic validation of a skill"""
    skill_path = Path(skill_path)

    # Check SKILL.md exists
    skill_md = skill_path / 'SKILL.md'
    if not skill_md.exists():
        return False, "SKILL.md not found"

    # Read and validate frontmatter
    content = skill_md.read_text()
    if not content.startswith('---'):
        return False, "No YAML frontmatter found"

    # Extract frontmatter
    match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
    if not match:
        return False, "Invalid frontmatter format"

    frontmatter_text = match.group(1)

    # Parse YAML frontmatter
    try:
        frontmatter = yaml.safe_load(frontmatter_text)
        if not isinstance(frontmatter, dict):
            return False, "Frontmatter must be a YAML dictionary"
    except yaml.YAMLError as e:
        return False, f"Invalid YAML in frontmatter: {e}"

    # Define allowed properties
    ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata'}

    # Check for unexpected properties (excluding nested keys under metadata)
    unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES
    if unexpected_keys:
        return False, (
            f"Unexpected key(s) in SKILL.md frontmatter: {', '.join(sorted(unexpected_keys))}. "
            f"Allowed properties are: {', '.join(sorted(ALLOWED_PROPERTIES))}"
        )

    # Check required fields
    if 'name' not in frontmatter:
        return False, "Missing 'name' in frontmatter"
    if 'description' not in frontmatter:
        return False, "Missing 'description' in frontmatter"

    # Extract name for validation
    name = frontmatter.get('name', '')
    if not isinstance(name, str):
        return False, f"Name must be a string, got {type(name).__name__}"
    name = name.strip()
    if name:
        # Check naming convention (hyphen-case: lowercase with hyphens)
        if not re.match(r'^[a-z0-9-]+$', name):
            return False, f"Name '{name}' should be hyphen-case (lowercase letters, digits, and hyphens only)"
        if name.startswith('-') or name.endswith('-') or '--' in name:
            return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens"
        # Check name length (max 64 characters per spec)
        if len(name) > 64:
            return False, f"Name is too long ({len(name)} characters). Maximum is 64 characters."

    # Extract and validate description
    description = frontmatter.get('description', '')
    if not isinstance(description, str):
        return False, f"Description must be a string, got {type(description).__name__}"
    description = description.strip()
    if description:
        # Check for angle brackets
        if '<' in description or '>' in description:
            return False, "Description cannot contain angle brackets (< or >)"
        # Check description length (max 1024 characters per spec)
        if len(description) > 1024:
            return False, f"Description is too long ({len(description)} characters). Maximum is 1024 characters."

    return True, "Skill is valid!"

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("Usage: python quick_validate.py <skill_directory>")
        sys.exit(1)
    
    valid, message = validate_skill(sys.argv[1])
    print(message)
    sys.exit(0 if valid else 1)
FILE:scripts/init_skill.py
#!/usr/bin/env python3
"""
Skill Initializer - Creates a new skill from template

Usage:
    init_skill.py <skill-name> --path <path>

Examples:
    init_skill.py my-new-skill --path skills/public
    init_skill.py my-api-helper --path skills/private
    init_skill.py custom-skill --path /custom/location
"""

import sys
from pathlib import Path


SKILL_TEMPLATE = """---
name: {skill_name}
description: [TODO: Complete and informative explanation of what the skill does and when to use it. Include WHEN to use this skill - specific scenarios, file types, or tasks that trigger it.]
---

# {skill_title}

## Overview

[TODO: 1-2 sentences explaining what this skill enables]

## Resources

This skill includes example resource directories that demonstrate how to organize different types of bundled resources:

### scripts/
Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.

### references/
Documentation and reference material intended to be loaded into context to inform Claude's process and thinking.

### assets/
Files not intended to be loaded into context, but rather used within the output Claude produces.

---

**Any unneeded directories can be deleted.** Not every skill requires all three types of resources.
"""

EXAMPLE_SCRIPT = '''#!/usr/bin/env python3
"""
Example helper script for {skill_name}

This is a placeholder script that can be executed directly.
Replace with actual implementation or delete if not needed.
"""

def main():
    print("This is an example script for {skill_name}")
    # TODO: Add actual script logic here

if __name__ == "__main__":
    main()
'''

EXAMPLE_REFERENCE = """# Reference Documentation for {skill_title}

This is a placeholder for detailed reference documentation.
Replace with actual reference content or delete if not needed.
"""

EXAMPLE_ASSET = """# Example Asset File

This placeholder represents where asset files would be stored.
Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed.
"""


def title_case_skill_name(skill_name):
    """Convert hyphenated skill name to Title Case for display."""
    return ' '.join(word.capitalize() for word in skill_name.split('-'))


def init_skill(skill_name, path):
    """Initialize a new skill directory with template SKILL.md."""
    skill_dir = Path(path).resolve() / skill_name

    if skill_dir.exists():
        print(f"❌ Error: Skill directory already exists: {skill_dir}")
        return None

    try:
        skill_dir.mkdir(parents=True, exist_ok=False)
        print(f"✅ Created skill directory: {skill_dir}")
    except Exception as e:
        print(f"❌ Error creating directory: {e}")
        return None

    skill_title = title_case_skill_name(skill_name)
    skill_content = SKILL_TEMPLATE.format(skill_name=skill_name, skill_title=skill_title)

    skill_md_path = skill_dir / 'SKILL.md'
    try:
        skill_md_path.write_text(skill_content)
        print("✅ Created SKILL.md")
    except Exception as e:
        print(f"❌ Error creating SKILL.md: {e}")
        return None

    try:
        scripts_dir = skill_dir / 'scripts'
        scripts_dir.mkdir(exist_ok=True)
        example_script = scripts_dir / 'example.py'
        example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name))
        example_script.chmod(0o755)
        print("✅ Created scripts/example.py")

        references_dir = skill_dir / 'references'
        references_dir.mkdir(exist_ok=True)
        example_reference = references_dir / 'api_reference.md'
        example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title))
        print("✅ Created references/api_reference.md")

        assets_dir = skill_dir / 'assets'
        assets_dir.mkdir(exist_ok=True)
        example_asset = assets_dir / 'example_asset.txt'
        example_asset.write_text(EXAMPLE_ASSET)
        print("✅ Created assets/example_asset.txt")
    except Exception as e:
        print(f"❌ Error creating resource directories: {e}")
        return None

    print(f"\n✅ Skill '{skill_name}' initialized successfully at {skill_dir}")
    return skill_dir


def main():
    if len(sys.argv) < 4 or sys.argv[2] != '--path':
        print("Usage: init_skill.py <skill-name> --path <path>")
        sys.exit(1)

    skill_name = sys.argv[1]
    path = sys.argv[3]

    print(f"🚀 Initializing skill: {skill_name}")
    print(f"   Location: {path}")
    print()

    result = init_skill(skill_name, path)
    sys.exit(0 if result else 1)


if __name__ == "__main__":
    main()
FILE:scripts/package_skill.py
#!/usr/bin/env python3
"""
Skill Packager - Creates a distributable .skill file of a skill folder

Usage:
    python utils/package_skill.py <path/to/skill-folder> [output-directory]

Example:
    python utils/package_skill.py skills/public/my-skill
    python utils/package_skill.py skills/public/my-skill ./dist
"""

import sys
import zipfile
from pathlib import Path
from quick_validate import validate_skill


def package_skill(skill_path, output_dir=None):
    """Package a skill folder into a .skill file."""
    skill_path = Path(skill_path).resolve()

    if not skill_path.exists():
        print(f"❌ Error: Skill folder not found: {skill_path}")
        return None

    if not skill_path.is_dir():
        print(f"❌ Error: Path is not a directory: {skill_path}")
        return None

    skill_md = skill_path / "SKILL.md"
    if not skill_md.exists():
        print(f"❌ Error: SKILL.md not found in {skill_path}")
        return None

    print("🔍 Validating skill...")
    valid, message = validate_skill(skill_path)
    if not valid:
        print(f"❌ Validation failed: {message}")
        print("   Please fix the validation errors before packaging.")
        return None
    print(f"✅ {message}\n")

    skill_name = skill_path.name
    if output_dir:
        output_path = Path(output_dir).resolve()
        output_path.mkdir(parents=True, exist_ok=True)
    else:
        output_path = Path.cwd()

    skill_filename = output_path / f"{skill_name}.skill"

    try:
        with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
            for file_path in skill_path.rglob('*'):
                if file_path.is_file():
                    arcname = file_path.relative_to(skill_path.parent)
                    zipf.write(file_path, arcname)
                    print(f"  Added: {arcname}")

        print(f"\n✅ Successfully packaged skill to: {skill_filename}")
        return skill_filename

    except Exception as e:
        print(f"❌ Error creating .skill file: {e}")
        return None


def main():
    if len(sys.argv) < 2:
        print("Usage: python utils/package_skill.py <path/to/skill-folder> [output-directory]")
        sys.exit(1)

    skill_path = sys.argv[1]
    output_dir = sys.argv[2] if len(sys.argv) > 2 else None

    print(f"📦 Packaging skill: {skill_path}")
    if output_dir:
        print(f"   Output directory: {output_dir}")
    print()

    result = package_skill(skill_path, output_dir)
    sys.exit(0 if result else 1)


if __name__ == "__main__":
    main()

Agent Skill Meta+1

F@f

claude-md-master

Kỹ năng

Kỹ năng tổng thể cho vòng đời tệp CLAUDE.md: tạo mới, cập nhật và cải thiện các tệp bằng dữ liệu đã được xác minh trực tiếp từ kho mã nguồn (repo), có hỗ trợ đa mô-đun và các quy tắc đặc thù theo từng ngăn xếp công nghệ (stack).

---
name: claude-md-master
description: Kỹ năng tổng thể cho vòng đời tệp CLAUDE.md - tạo mới, cập nhật, cải thiện với nội dung được xác minh từ kho mã nguồn và hỗ trợ đa mô-đun. Sử dụng khi tạo mới hoặc cập nhật các tệp CLAUDE.md.
---

# CLAUDE.md Master (Tạo mới/Cập nhật/Cải thiện)

## Khi nào nên sử dụng
- Người dùng yêu cầu tạo mới, cải thiện, cập nhật hoặc chuẩn hóa các tệp CLAUDE.md.

## Các quy tắc cốt lõi
- Chỉ đưa vào những thông tin đã được xác minh thực tế trong kho mã nguồn (repo) hoặc tệp cấu hình.
- Không bao giờ đưa vào bí mật (secrets), mã thông báo (tokens), thông tin xác thực hay dữ liệu cá nhân của người dùng.
- Không bao giờ đưa vào các hướng dẫn tạm thời hoặc chỉ dành riêng cho một tác vụ cụ thể.
- Giữ ngắn gọn súc tích: tệp gốc (root) <= 200 dòng, tệp mô-đun <= 120 dòng.
- Sử dụng danh sách gạch đầu dòng; tránh viết văn xuôi dài dòng.
- Các câu lệnh phải có thể sao chép và dán (copy-pasteable) trực tiếp và lấy nguồn từ tài liệu/scripts/CI của repo.
- Bỏ qua các phần trống; tránh viết nội dung lấp chỗ trống vô nghĩa.

## Dữ liệu đầu vào bắt buộc (phải phân tích trước khi tạo)
- Cấu hình biên dịch/quản lý gói liên quan đến ngăn xếp công nghệ (stack) được phát hiện (cả ở thư mục gốc + các mô-đun).
- Cấu hình phân tích mã tĩnh (static analysis) được sử dụng trong repo (nếu có).
- Cấu trúc mô-đun thực tế và các khuôn mẫu mã nguồn (quét các thư mục/tệp thực tế).
- Các thư mục mã nguồn gốc đại diện cho mỗi mô-đun để trích xuất:
  cấu trúc gói/tính năng, các kiểu dữ liệu chính và các chú thích (annotations) đang được sử dụng.

## Khám phá kho mã nguồn (nhanh + có trọng tâm)
1. Định vị các biến thể CLAUDE.md hiện có: `CLAUDE.md`, `.claude.md`, `.claude.local.md`.
2. Xác định ngăn xếp công nghệ (stack) và các điểm khởi đầu (entry points) thông qua việc đọc tối thiểu:
   - `README.md`, các tệp `docs/*` có liên quan
   - Các tệp biên dịch/quản lý gói (xem tài liệu tham chiếu theo từng stack)
   - Môi trường chạy/cấu hình: `Dockerfile`, `docker-compose.yml`, `.env.example`, `config/*`
   - CI: `.github/workflows/*`, `.gitlab-ci.yml`, `.circleci/*`
3. Chỉ trích xuất các câu lệnh nếu chúng thực sự tồn tại trong các script/cấu hình/tài liệu của repo.
4. Phát hiện cấu trúc đa mô-đun:
   - Android/Gradle: đọc các khai báo include trong `settings.gradle` hoặc `settings.gradle.kts`.
   - iOS: phát hiện nhiều targets/workspaces trong `*.xcodeproj`/`*.xcworkspace`.
   - Nếu có nhiều hơn một mô-đun/target sở hữu thư mục `src/` hoặc cấu hình biên dịch riêng, hãy lên kế hoạch tạo các tệp CLAUDE.md cấp mô-đun.
5. Với mỗi ứng viên mô-đun, hãy đọc tệp biên dịch của nó + tài liệu tối thiểu để nắm bắt
   mục đích riêng, các điểm khởi đầu và các câu lệnh của mô-đun đó.
6. Quét các thư mục mã nguồn gốc để tìm:
   - Các thư mục gói/tính năng cấp cao nhất và các quy ước phân tầng kiến trúc.
   - Các chú thích (annotations)/kiểu dữ liệu chính đang được sử dụng (theo tài liệu tham chiếu của stack).
   - Các quy ước đặt tên được sử dụng trong kho mã nguồn.
7. Ghi nhận các luồng công việc không hiển nhiên hoặc những điểm dễ vấp phải (gotchas) từ tài liệu hoặc các khuôn mẫu mã nguồn.

Hiệu năng:
- Ưu tiên liệt kê danh sách tệp + đọc có mục tiêu.
- Tránh đọc toàn bộ tệp khi chỉ cần một phần hoặc một ký hiệu (symbol) là đủ.
- Bỏ qua các thư mục lớn: `node_modules`, `vendor`, `build`, `dist`.

## Tài liệu tham chiếu đặc thù theo Stack (Mẫu 2)
Chỉ đọc tài liệu tham chiếu liên quan khi xuất hiện các dấu hiệu nhận diện tương ứng:
- Android/Gradle → `references/android.md`
- iOS/Xcode/Swift → `references/ios.md`
- PHP → `references/php.md`
- Go → `references/go.md`
- React (web) → `references/react-web.md`
- React Native → `references/react-native.md`
- Rust → `references/rust.md`
- Python → `references/python.md`
- Java/JVM → `references/java.md`
- Bộ công cụ Node → `references/node.md`
- .NET/C# → `references/dotnet.md`
- Dart/Flutter → `references/flutter.md`
- Ruby/Rails → `references/ruby.md`
- Elixir/Erlang → `references/elixir.md`
- C/C++/CMake → `references/cpp.md`
- Khác/Chưa rõ → `references/generic.md` (dự phòng khi không khớp với tài liệu tham chiếu cụ thể nào)

Nếu phát hiện nhiều ngăn xếp công nghệ (stacks), hãy đọc nhiều tài liệu tham chiếu tương ứng.
Nếu không nhận diện được stack nào, hãy sử dụng tài liệu tham chiếu chung (generic).

## Chính sách đầu ra đa mô-đun (bắt buộc khi phát hiện thấy)
- Luôn tạo một tệp `CLAUDE.md` ở thư mục gốc (root).
- Đồng thời tạo tệp `CLAUDE.md` bên trong từng thư mục gốc của mô-đun/target có ý nghĩa.
  - "Có ý nghĩa" = có tệp cấu hình biên dịch riêng và thư mục `src/` (hoặc tương đương).
  - Bỏ qua các thư mục chỉ chứa công cụ phụ trợ như `buildSrc`, `gradle`, `scripts`, `tools`.
- Tệp của mô-đun phải mang tính đặc thù riêng cho mô-đun đó và tránh lặp lại nội dung chung:
  - Bao gồm mục đích, các đường dẫn chính, điểm khởi đầu, kiểm thử của mô-đun và các câu lệnh
    riêng của mô-đun (nếu có).
  - Tham chiếu đến thông tin dùng chung thông qua `@/CLAUDE.md`.

## Chính sách CLAUDE.md cho mô-đun nghiệp vụ (áp dụng cho mọi stack)
Đối với các thư mục chứa logic nghiệp vụ trong monorepo (`src/`, `lib/`, `packages/`, `internal/`):
- Tạo `CLAUDE.md` cho các mô-đun có >5 tệp HOẶC có tệp README riêng
- Bỏ qua các thư mục chỉ chứa tiện ích: `Helper`, `Utils`, `Common`, `Shared`, `Exception`, `Trait`, `Constants`
- Không bắt buộc phải có cấu trúc phân tầng; hãy cung cấp thông tin mô-đun bất kể kiến trúc nào
- Tối đa 120 dòng cho mỗi tệp CLAUDE.md cấp mô-đun
- Tham chiếu tệp gốc qua `@/CLAUDE.md` đối với kiến trúc/khuôn mẫu dùng chung
- Bao gồm: mục đích, cấu trúc, các lớp (classes) chính, các phụ thuộc, điểm khởi đầu

## Các phần đầu ra bắt buộc (cho mỗi tệp CLAUDE.md cấp mô-đun)
Đưa các phần này vào nếu phát hiện thấy trong kho mã nguồn (chỉ bỏ qua nếu không có):
- **Danh mục tính năng/thành phần (Feature/component inventory)**: liệt kê các thư mục cấp cao nhất nằm dưới thư mục mã nguồn gốc
- **Các mô-đun cốt lõi/dùng chung (Core/shared modules)**: các thư mục mã tiện ích, chung hoặc chia sẻ
- **Cấu trúc điều hướng/định tuyến (Navigation/routing structure)**: sơ đồ điều hướng, các tuyến đường (routes) hoặc bộ định tuyến (routers)
- **Mẫu tầng mạng/API (Network/API layer pattern)**: các trình khách API (API clients), điểm cuối (endpoints), lớp bọc phản hồi (response wrappers)
- **Mẫu tiêm phụ thuộc (DI/injection pattern)**: các mô-đun, thùng chứa (containers) hoặc thiết lập tiêm phụ thuộc
- **Các tệp biên dịch/cấu hình (Build/config files)**: các cấu hình riêng của mô-đun (proguard, manifests, v.v.)

Xem các tài liệu tham chiếu đặc thù theo từng stack để biết chính xác các khuôn mẫu cần phát hiện và báo cáo.

## Quy trình cập nhật (bắt buộc tuân thủ)
1. Chỉ đề xuất các nội dung bổ sung có trọng tâm; hiển thị phần khác biệt (diffs) cho từng tệp.

2. Xin phê duyệt trước khi áp dụng các cập nhật:

**Cursor IDE:**
Sử dụng công cụ AskQuestion với các tùy chọn sau:
- id: "approval"
- prompt: "Apply these CLAUDE.md updates?"
- options: [{"id": "yes", "label": "Yes, apply"}, {"id": "no", "label": "No, cancel"}]

**Claude Code (Terminal):**
Xuất ra các thay đổi được đề xuất và hỏi:
"Do you approve these updates? (yes/no)"
Dừng lại và chờ phản hồi của người dùng trước khi tiếp tục.

**Các Môi trường Khác (Dự phòng):**
Nếu không có sẵn công cụ đặt câu hỏi có cấu trúc:
1. Hiển thị rõ ràng các thay đổi được đề xuất
2. Hỏi: "Do you approve these updates? Reply 'yes' to apply or 'no' to cancel."
3. Chờ xác nhận rõ ràng từ người dùng trước khi tiếp tục

3. Áp dụng các cập nhật, đồng thời bảo toàn các nội dung tùy chỉnh sẵn có.

Nếu chưa có tệp CLAUDE.md nào tồn tại, hãy đề xuất tạo tệp mới để xin phê duyệt.

## Quy tắc trích xuất nội dung (bắt buộc)
- Chỉ lấy từ kho mã nguồn (codebase):
  - Trích xuất: tên kiểu dữ liệu/lớp/chú thích (annotation) đang được sử dụng, các mẫu đường dẫn thực tế,
    các quy ước đặt tên.
  - Tuyệt đối không đưa vào: các giá trị gắn cứng (hardcoded), bí mật (secrets), khóa API, logic nghiệp vụ cụ thể.
  - Tuyệt đối không đưa vào: các đoạn mã ví dụ (code snippets) trong phần quy tắc Nên làm/Không nên làm (Do/Do Not).

## Xác minh trước khi ghi tệp
- [ ] Mọi quy tắc đều tham chiếu đến các kiểu dữ liệu/đường dẫn thực tế từ kho mã nguồn
- [ ] Không có ví dụ mã nguồn trong các phần Nên làm/Không nên làm (Do/Do Not)
- [ ] Các khuôn mẫu khớp với những gì thực sự có trong kho mã nguồn (không bị lỗi thời)

## Quy tắc nội dung
- Bao gồm: các câu lệnh, tóm tắt kiến trúc, đường dẫn chính, kiểm thử, những điểm dễ vấp phải (gotchas), đặc thù quy trình làm việc.
- Loại trừ: các phương pháp thực hành tốt nhất chung chung, thông tin hiển nhiên, các nhận định chưa được kiểm chứng.
- Sử dụng cú pháp nhập `@path/to/file` để tránh trùng lặp nội dung.
- Định dạng Nên làm/Không nên làm (Do/Do Not) là tùy chọn; chỉ giữ lại nếu định dạng đó đã được sử dụng sẵn trong tệp.
- Tránh đưa vào các ví dụ mã nguồn ngoại trừ những câu lệnh ngắn dùng để sao chép và dán.

## Chiến lược xử lý tệp hiện có
Phát hiện:
- Nếu dòng đánh dấu `<!-- Generated by claude-md-editor skill -->` đã tồn tại → đây là lần chạy tiếp theo
- Ngược lại → đây là lần chạy đầu tiên

Lần chạy đầu tiên + đã có tệp tồn tại:
- Sao lưu `CLAUDE.md` → `CLAUDE.md.bak`
- Sử dụng tệp `.bak` làm nguồn tham khảo và chỉ trích xuất những thông tin đặc thù của dự án có thể tái sử dụng
- Tạo một tệp mới ngắn gọn súc tích và thêm dòng đánh dấu vào

Lần chạy tiếp theo:
- Bảo toàn các phần tùy chỉnh và cách diễn đạt riêng trừ khi chúng đã lỗi thời hoặc không còn chính xác
- Chỉ cập nhật những nội dung mâu thuẫn với trạng thái hiện tại của kho mã nguồn
- Chỉ thêm các phần còn thiếu nếu chúng thực sự mang lại giá trị

Tuyệt đối không bao giờ sửa đổi tệp `.claude.local.md`.

## Đầu ra
Sau khi cập nhật xong, hãy in ra một bản báo cáo ngắn gọn:
```
## CLAUDE.md Update Report
- /CLAUDE.md [CREATED | BACKED_UP+CREATED | UPDATED]
- /<module>/CLAUDE.md [CREATED | UPDATED]
- Backups: list any `.bak` files
```

## Danh sách kiểm tra xác thực (Validation checklist)
- Phần mô tả cụ thể và có bao gồm các thuật ngữ kích hoạt (trigger terms)
- Không còn sót lại bất kỳ biến giữ chỗ (placeholders) nào
- Không chứa bất kỳ thông tin bí mật (secrets) nào
- Các câu lệnh đều có thật và có thể sao chép-dán để chạy ngay
- Tuân thủ quy tắc báo cáo trước khi ghi (report-first rule)
- Các tài liệu tham chiếu chỉ sâu một cấp duy nhất
FILE:README.md
# claude-md-master

Kỹ năng tổng thể cho vòng đời tệp CLAUDE.md: tạo mới, cập nhật và cải thiện các tệp
bằng dữ liệu đã được xác minh trực tiếp từ kho mã nguồn (repo), có hỗ trợ đa mô-đun và các quy tắc đặc thù theo từng ngăn xếp công nghệ (stack).

## Tổng quan
- Mục tiêu: tạo ra các tệp `CLAUDE.md` chính xác, ngắn gọn từ dữ liệu thực tế của repo
- Phạm vi: thư mục gốc (root) + các mô-đun có ý nghĩa, với cơ chế phát hiện đặc thù theo từng stack
- Cơ chế bảo vệ: không lộ bí mật (secrets), không thêm lời lẽ rườm rà, phải có sự phê duyệt rõ ràng trước khi ghi tệp

## Cách AI khám phá và sử dụng kỹ năng này
- Khám phá: công cụ nhận biết kỹ năng này vì nó tồn tại trong
  danh mục kỹ năng của repo (đã được cài đặt/có sẵn trong môi trường)
- Tự động sử dụng: khi một yêu cầu có chứa cụm "tạo/cập nhật/cải thiện
  CLAUDE.md", công cụ sẽ chọn kỹ năng này làm kết quả khớp phù hợp nhất
- Sử dụng thủ công: người vận hành có thể gọi trực tiếp lệnh `/claude-md-master`
  để buộc thực thi quy trình này
- Hành vi khi chạy: quét tài liệu/cấu hình/mã nguồn của repo, đề xuất các thay đổi,
  và chờ phê duyệt rõ ràng trước khi ghi ra tệp

## Đối tượng sử dụng
- Người vận hành AI sử dụng các kỹ năng trong Cursor/Claude Code
- Những người bảo trì phát triển và cập nhật bộ quy tắc cùng tài liệu tham chiếu

## Kỹ năng này làm gì
- Tạo mới hoặc cập nhật tệp `CLAUDE.md` với nội dung được trích xuất và xác minh từ chính repo
- Thực thi nghiêm ngặt các quy tắc về an toàn và tính cô đọng (không chứa secrets, không viết lan man)
- Phát hiện các repo đa mô-đun và tạo tệp `CLAUDE.md` ở cấp độ từng mô-đun
- Sử dụng các tài liệu tham chiếu đặc thù theo từng stack để nắm bắt chính xác các khuôn mẫu kiến trúc

## Khi nào nên sử dụng
- Người dùng yêu cầu tạo mới, cải thiện, cập nhật hoặc chuẩn hóa tệp `CLAUDE.md`
- Kho mã nguồn cần một tài liệu hướng dẫn nhất quán, đã được kiểm chứng cho các luồng công việc AI

## Dữ liệu đầu vào bắt buộc (phải được phân tích)
- Tài liệu repo: `README.md`, `docs/*` (nếu có)
- Các tệp biên dịch/cấu hình liên quan đến (các) stack được phát hiện
- Môi trường chạy/cấu hình: `Dockerfile`, `.env.example`, `config/*` (nếu có)
- CI: `.github/workflows/*`, `.gitlab-ci.yml`, `.circleci/*` (nếu có)
- Các thư mục mã nguồn gốc để trích xuất cấu trúc thực tế, kiểu dữ liệu, chú thích (annotations), quy ước đặt tên

## Đầu ra
- Tệp `CLAUDE.md` ở thư mục gốc (luôn luôn có)
- Tệp `CLAUDE.md` cấp mô-đun cho các mô-đun có ý nghĩa (có cấu hình biên dịch riêng + thư mục `src/`)
- Báo cáo cập nhật ngắn gọn liệt kê các tệp đã tạo mới/cập nhật và các tệp sao lưu (backups)

## Quy trình làm việc (tổng quan)
1. Định vị các biến thể `CLAUDE.md` hiện có và xác định đây là lần chạy đầu tiên hay lần chạy tiếp theo
2. Xác định (các) ngăn xếp công nghệ và cấu trúc đa mô-đun
3. Đọc các tài liệu/cấu hình/CI liên quan để lấy các câu lệnh và quy trình làm việc thực tế
4. Quét các thư mục mã nguồn gốc để nắm bắt cấu trúc, kiểu dữ liệu chính, chú thích, khuôn mẫu
5. Tạo tệp ở thư mục gốc + các tệp mô-đun, tránh trùng lặp nội dung thông qua tham chiếu `@/CLAUDE.md`
6. Yêu cầu phê duyệt rõ ràng trước khi áp dụng các cập nhật
7. Áp dụng thay đổi và in báo cáo cập nhật

## Các quy tắc và ràng buộc cốt lõi
- Chỉ đưa vào thông tin đã được xác minh trong repo; tuyệt đối không thêm bí mật (secrets)
- Giữ ngắn gọn: tệp gốc <= 200 dòng, tệp mô-đun <= 120 dòng
- Các câu lệnh phải có thật và sao chép-dán để chạy được ngay từ tài liệu/scripts/CI của repo
- Bỏ qua các mục trống; tránh viết những lời khuyên chung chung
- Không bao giờ sửa đổi tệp `.claude.local.md`
- Tránh đưa các ví dụ mã nguồn vào phần Nên làm/Không nên làm (Do/Do Not)

## Chính sách đa mô-đun (tóm tắt)
- Luôn tạo tệp `CLAUDE.md` ở thư mục gốc
- Chỉ tạo các tệp cấp mô-đun cho những mô-đun thực sự có ý nghĩa
- Bỏ qua các thư mục chỉ chứa công cụ phụ trợ (ví dụ: `buildSrc`, `gradle`, `scripts`, `tools`)
- Các mô-đun nghiệp vụ sẽ có tệp riêng khi chứa >5 tệp hoặc có tệp README riêng

## Tài liệu tham chiếu (hướng dẫn đặc thù theo từng stack)
Mỗi tài liệu tham chiếu định nghĩa rõ các dấu hiệu nhận diện, nguồn phân tích trước khi tạo, mục tiêu
quét mã nguồn, các mục đầu ra bắt buộc, nguồn câu lệnh và các đường dẫn chính.

- `references/android.md` — Android/Gradle
- `references/ios.md` — iOS/Xcode/Swift
- `references/react-web.md` — Ứng dụng web React
- `references/react-native.md` — React Native
- `references/node.md` — Bộ công cụ Node (phổ quát)
- `references/python.md` — Python
- `references/java.md` — Java/JVM
- `references/dotnet.md` — .NET (C#/F#)
- `references/go.md` — Go
- `references/rust.md` — Rust
- `references/flutter.md` — Dart/Flutter
- `references/ruby.md` — Ruby/Rails
- `references/php.md` — PHP (Laravel/Symfony/CI/Phalcon)
- `references/elixir.md` — Elixir/Erlang
- `references/cpp.md` — C/C++
- `references/generic.md` — Dự phòng khi không khớp với stack cụ thể nào

## Mở rộng kỹ năng
- Thêm một tệp `references/<stack>.md` mới theo cùng cấu trúc biểu mẫu
- Giữ cho các dấu hiệu nhận diện và các mục đầu ra bắt buộc luôn cụ thể và có thể kiểm chứng được
- Không đưa vào các câu lệnh chưa được kiểm chứng hoặc những lời khuyên chung chung

## Danh sách kiểm tra chất lượng
- Mọi quy tắc đều tham chiếu đến các kiểu dữ liệu/đường dẫn thực tế từ repo
- Không còn sót lại biến giữ chỗ (placeholders) nào
- Không chứa thông tin bí mật (secrets)
- Các câu lệnh đều có thật và có thể sao chép-dán để dùng ngay
- Tuân thủ quy tắc báo cáo trước; các tài liệu tham chiếu chỉ sâu một cấp duy nhất
FILE:references/android.md
# Android (Gradle)

## Dấu hiệu nhận diện
- `settings.gradle` hoặc `settings.gradle.kts`
- `build.gradle` hoặc `build.gradle.kts`
- `gradle.properties`
- `gradle/libs.versions.toml`
- `gradlew`
- `gradle/wrapper/gradle-wrapper.properties`
- `app/src/main/AndroidManifest.xml`

## Dấu hiệu đa mô-đun (Multi-module)
- Có nhiều khai báo `include(...)` hoặc `includeBuild(...)` trong `settings.gradle*`
- Có nhiều hơn một thư mục mô-đun chứa `build.gradle*` và `src/`
- Các thư mục gốc mô-đun phổ biến như `feature/`, `core/`, `library/` (nếu có)

## Trước khi tạo, hãy phân tích các nguồn sau
- `settings.gradle` hoặc `settings.gradle.kts`
- `build.gradle` hoặc `build.gradle.kts` (cả ở thư mục gốc và các mô-đun)
- `gradle/libs.versions.toml`
- `gradle.properties`
- `config/detekt/detekt.yml` (nếu có)
- `app/src/main/AndroidManifest.xml` (hoặc tệp manifest của các mô-đun)

## Quét kho mã nguồn (Đặc thù cho Android)
- Thư mục mã nguồn gốc trên mỗi mô-đun: `*/src/main/java/`, `*/src/main/kotlin/`
- Cây gói (package tree) cho các thư mục tính năng/phân tầng (chỉ ghi nhận nếu có mặt):
  `features/`, `core/`, `common/`, `data/`, `domain/`, `presentation/`,
  `ui/`, `di/`, `navigation/`, `network/`
- Cách sử dụng chú thích - Annotation (chỉ ghi nhận nếu có mặt):
  Hilt (`@HiltAndroidApp`, `@AndroidEntryPoint`, `@HiltViewModel`,
  `@Module`, `@InstallIn`, `@Provides`, `@Binds`),
  Compose (`@Composable`, `@Preview`),
  Room (`@Entity`, `@Dao`, `@Database`),
  WorkManager (`@HiltWorker`, `ListenableWorker`, `CoroutineWorker`),
  Serialization (`@Serializable`, `@Parcelize`),
  Retrofit (`@GET`, `@POST`, `@PUT`, `@DELETE`, `@Body`, `@Query`)
- Các mẫu điều hướng (chỉ ghi nhận nếu có mặt): `NavHost`, `composable`

## Đầu ra bắt buộc (tệp CLAUDE.md cho mô-đun Android)
Đưa các mục này vào nếu phát hiện thấy (liệt kê tên thực tế tìm được):
- **Danh mục tính năng (Features inventory)**: liệt kê các thư mục dưới `features/` (ví dụ: homepage, payment, auth)
- **Các mô-đun cốt lõi (Core modules)**: liệt kê các thư mục dưới `core/` (ví dụ: data, network, localization)
- **Sơ đồ điều hướng (Navigation graphs)**: liệt kê các tệp `*Graph.kt` hoặc `*Navigator*.kt`
- **Các mô-đun Hilt (Hilt modules)**: liệt kê các lớp gắn `@Module` hoặc nội dung gói `di/`
- **Các API Retrofit**: liệt kê các giao diện (interfaces) `*Api.kt`
- **Cơ sở dữ liệu Room**: liệt kê các lớp gắn `@Database`
- **Workers**: liệt kê các lớp gắn `@HiltWorker`
- **Proguard**: đề cập đến tệp `proguard-rules.pro` nếu có mặt

## Nguồn câu lệnh
- README/docs hoặc CI gọi thực thi Gradle wrapper
- Các script trong repo gọi `./gradlew`
- Cách dùng `./gradlew assemble`, `./gradlew test`, `./gradlew lint` trong tài liệu/scripts
- Chỉ đưa vào những câu lệnh thực sự tồn tại trong kho mã nguồn

## Các đường dẫn chính cần đề cập (chỉ khi có mặt)
- `app/src/main/`, `app/src/main/res/`
- `app/src/main/java/`, `app/src/main/kotlin/`
- `app/src/test/`, `app/src/androidTest/`
FILE:references/cpp.md
# C / C++

## Dấu hiệu nhận diện
- `CMakeLists.txt`
- `meson.build`
- `Makefile`
- `conanfile.*`, `vcpkg.json`
- `compile_commands.json`
- `src/`, `include/`

## Dấu hiệu đa mô-đun (Multi-module)
- `CMakeLists.txt` có chứa `add_subdirectory(...)`
- Nhiều tệp `CMakeLists.txt` hoặc `meson.build` trong các thư mục con
- Các thư mục `libs/`, `apps/`, hoặc `modules/` có tệp biên dịch riêng

## Trước khi tạo, hãy phân tích các nguồn này
- `CMakeLists.txt` / `meson.build` / `Makefile`
- `conanfile.*`, `vcpkg.json` (nếu có)
- `compile_commands.json` (nếu có)
- `src/`, `include/`, `tests/`, `libs/`

## Quét codebase (đặc thù C/C++)
- Các thư mục gốc mã nguồn: `src/`, `include/`, `tests/`, `libs/`
- Phân tách thư viện/ứng dụng (chỉ ghi nhận nếu có):
  `src/lib`, `src/app`, `src/bin`
- Các không gian tên (namespaces) và tiền tố lớp (chỉ ghi nhận nếu có)
- Các đích dựng (targets) của CMake (chỉ ghi nhận nếu có):
  `add_library`, `add_executable`

## Đầu ra bắt buộc (CLAUDE.md cho mô-đun C/C++)
Bao gồm những mục này nếu phát hiện thấy (liệt kê tên thực tế tìm được):
- **Thư viện (Libraries)**: liệt kê các đích dựng thư viện
- **Tệp thực thi (Executables)**: liệt kê các đích dựng thực thi
- **Tệp tiêu đề (Headers)**: liệt kê các thư mục chứa tệp header công khai
- **Mô-đun/thành phần (Modules/components)**: liệt kê các thư mục con có tệp cấu hình dựng (build files)
- **Phụ thuộc (Dependencies)**: liệt kê các gói phụ thuộc Conan/vcpkg (nếu có)

## Nguồn lấy lệnh thực thi
- README/tài liệu hoặc cấu hình CI gọi `cmake`, `ninja`, `make`, hoặc `meson`
- Các kịch bản (scripts) trong kho lưu trữ gọi tới công cụ dựng (build tools)
- Chỉ đưa vào các lệnh thực sự có mặt trong kho lưu trữ

## Các đường dẫn chính cần đề cập (chỉ khi có mặt)
- `src/`, `include/`
- `tests/`, `libs/`
FILE:references/dotnet.md
# .NET (C# / F#)

## Tín hiệu nhận diện
- `*.sln`
- `*.csproj`, `*.fsproj`, `*.vbproj`
- `global.json`
- `Directory.Build.props`, `Directory.Build.targets`
- `nuget.config`
- `Program.cs`
- `Startup.cs`
- `appsettings*.json`

## Tín hiệu đa mô-đun (Multi-module signals)
- Tệp `*.sln` chứa nhiều mục dự án
- Nhiều tệp `*.*proj` nằm dưới `src/` và `tests/`
- Các tệp `Directory.Build.*` quản lý thiết lập dùng chung xuyên suốt các dự án

## Trước khi tạo, hãy phân tích các nguồn này
- `*.sln`, `*.csproj` / `*.fsproj` / `*.vbproj`
- `Directory.Build.props`, `Directory.Build.targets`
- `global.json`, `nuget.config`
- `Program.cs` / `Startup.cs`
- `appsettings*.json`

## Quét codebase (đặc thù .NET)
- Các thư mục gốc mã nguồn: `src/`, `tests/`, các thư mục dự án có chứa `*.csproj`
- Các thư mục phân tầng (chỉ ghi nhận nếu có):
  `Controllers`, `Services`, `Repositories`, `Domain`, `Infrastructure`
- Các thuộc tính (attributes) của ASP.NET (chỉ ghi nhận nếu có):
  `[ApiController]`, `[Route]`, `[HttpGet]`, `[HttpPost]`, `[Authorize]`
- Việc sử dụng EF Core (chỉ ghi nhận nếu có):
  `DbContext`, `Migrations`, `[Key]`, `[Table]`

## Đầu ra bắt buộc (CLAUDE.md cho mô-đun .NET)
Bao gồm những mục này nếu phát hiện thấy (liệt kê tên thực tế tìm được):
- **Controllers**: liệt kê các lớp có gắn `[ApiController]`
- **Services**: liệt kê các lớp dịch vụ (service classes)
- **Repositories**: liệt kê các lớp kho lưu trữ dữ liệu (repository classes)
- **Entities**: liệt kê các lớp thực thể (entity classes) của EF Core
- **DbContext**: liệt kê các lớp ngữ cảnh cơ sở dữ liệu
- **Middleware**: liệt kê các middleware tùy chỉnh
- **Cấu hình (Configuration)**: liệt kê các mục cấu hình hoặc các lớp tùy chọn (options classes)

## Nguồn lấy lệnh thực thi
- README/tài liệu hoặc cấu hình CI gọi lệnh `dotnet`
- Các kịch bản trong kho lưu trữ như `build.ps1`, `build.sh`
- Cách sử dụng `dotnet run`, `dotnet test` trong tài liệu/kịch bản
- Chỉ đưa vào các lệnh thực sự có mặt trong kho lưu trữ

## Các đường dẫn chính cần đề cập (chỉ khi có mặt)
- `src/`, `tests/`
- `appsettings*.json`
- `Controllers/`, `Models/`, `Views/`, `wwwroot/`
FILE:references/elixir.md
# Elixir / Erlang

## Tín hiệu nhận diện
- `mix.exs`, `mix.lock`
- `config/config.exs`
- `lib/`, `test/`
- `apps/` (dự án dạng umbrella)
- `rel/`

## Tín hiệu đa mô-đun
- Cấu trúc Umbrella có thư mục `apps/` chứa nhiều tệp `mix.exs`
- Tệp `mix.exs` ở thư mục gốc có khai báo `apps_path`

## Trước khi tạo, hãy phân tích các nguồn này
- Tệp `mix.exs`, `mix.lock` ở thư mục gốc
- `config/config.exs`
- `apps/*/mix.exs` (dự án umbrella)
- `lib/`, `test/`, `rel/`

## Quét codebase (đặc thù Elixir)
- Các thư mục gốc mã nguồn: `lib/`, `test/`, `apps/*/lib` (dự án umbrella)
- Cấu trúc Phoenix (chỉ ghi nhận nếu có):
  `lib/*_web/`, `controllers`, `views`, `channels`, `routers`
- Việc sử dụng Ecto (chỉ ghi nhận nếu có):
  `schema`, `Repo`, `migrations`
- Các ngữ cảnh/mô-đun (chỉ ghi nhận nếu có):
  các mô-đun ngữ cảnh trong `lib/*/` và các tệp `*_context.ex`

## Đầu ra bắt buộc (CLAUDE.md cho mô-đun Elixir)
Bao gồm những mục này nếu phát hiện thấy (liệt kê tên thực tế tìm được):
- **Contexts**: liệt kê các mô-đun ngữ cảnh (context modules)
- **Schemas**: liệt kê các mô-đun lược đồ Ecto (Ecto schema modules)
- **Controllers**: liệt kê các mô-đun controller của Phoenix
- **Channels**: liệt kê các mô-đun kênh (channel) của Phoenix
- **Workers**: liệt kê các mô-đun xử lý tác vụ chạy ngầm (Oban, v.v.)
- **Umbrella apps**: liệt kê các ứng dụng con bên dưới dự án umbrella (nếu có)

## Nguồn lấy lệnh thực thi
- README/tài liệu hoặc cấu hình CI gọi lệnh `mix`
- Các kịch bản trong kho lưu trữ gọi tới `mix`
- Chỉ đưa vào các lệnh thực sự có mặt trong kho lưu trữ

## Các đường dẫn chính cần đề cập (chỉ khi có mặt)
- `lib/`, `test/`, `config/`
- `apps/`, `rel/`
FILE:references/flutter.md
# Dart / Flutter

## Tín hiệu nhận diện
- `pubspec.yaml`, `pubspec.lock`
- `analysis_options.yaml`
- `lib/`
- `android/`, `ios/`, `web/`, `macos/`, `windows/`, `linux/`

## Tín hiệu đa mô-đun
- `melos.yaml` (monorepo cho Flutter)
- Nhiều tệp `pubspec.yaml` nằm dưới `packages/`, `apps/`, hoặc `plugins/`

## Trước khi tạo, hãy phân tích các nguồn này
- `pubspec.yaml`, `pubspec.lock`
- `analysis_options.yaml`
- `melos.yaml` (nếu là monorepo)
- `lib/`, `test/`, và các thư mục nền tảng (`android/`, `ios/`, v.v.)

## Quét codebase (đặc thù Flutter)
- Các thư mục gốc mã nguồn: `lib/`, `test/`
- Điểm khởi chạy (chỉ ghi nhận nếu có): `lib/main.dart`
- Các thư mục phân tầng (chỉ ghi nhận nếu có):
  `features/`, `core/`, `data/`, `domain/`, `presentation/`
- Quản lý trạng thái (chỉ ghi nhận nếu có):
  `Bloc`, `Cubit`, `ChangeNotifier`, `Provider`, `Riverpod`
- Quy ước đặt tên Widget (chỉ ghi nhận nếu có):
  `*Screen`, `*Page`

## Đầu ra bắt buộc (CLAUDE.md cho mô-đun Flutter)
Bao gồm những mục này nếu phát hiện thấy (liệt kê tên thực tế tìm được):
- **Tính năng (Features)**: liệt kê các thư mục nằm dưới `features/` hoặc `lib/`
- **Mô-đun cốt lõi (Core modules)**: liệt kê các thư mục nằm dưới `core/` (nếu có)
- **Quản lý trạng thái (State management)**: liệt kê thiết lập Bloc/Cubit/Provider
- **Repositories**: liệt kê các lớp repository
- **Nguồn dữ liệu (Data sources)**: liệt kê các lớp nguồn dữ liệu từ xa/cục bộ (remote/local data sources)
- **Widgets**: liệt kê các thư mục chứa widget dùng chung

## Nguồn lấy lệnh thực thi
- README/tài liệu hoặc cấu hình CI gọi lệnh `flutter`
- Các kịch bản trong kho lưu trữ gọi tới `flutter` hoặc `dart`
- Cách sử dụng `flutter run`, `flutter test`, `flutter pub get` trong tài liệu/kịch bản
- Chỉ đưa vào các lệnh thực sự có mặt trong kho lưu trữ

## Các đường dẫn chính cần đề cập (chỉ khi có mặt)
- `lib/`, `test/`
- `android/`, `ios/`
FILE:references/generic.md
# Ngăn Xếp Công Nghệ Chung / Chưa Xác Định (Generic / Unknown Stack)

Sử dụng tài liệu tham chiếu này khi không có tài liệu tham chiếu ngăn xếp công nghệ cụ thể nào khớp với dự án.

## Tín hiệu nhận diện (các mẫu phổ biến)
- `README.md`, `CONTRIBUTING.md`
- `Makefile`, `Taskfile.yml`, `justfile`
- `Dockerfile`, `docker-compose.yml`
- `.env.example`, `config/`
- Các tệp cấu hình CI: `.github/workflows/`, `.gitlab-ci.yml`, `.circleci/`

## Trước khi tạo, hãy phân tích các nguồn này
- `README.md` - tổng quan dự án, hướng dẫn cài đặt, các lệnh thực thi
- Các tệp cấu hình dựng/quản lý gói ở thư mục gốc (bất kỳ định dạng nào có thể nhận diện được)
- `Makefile`, `Taskfile.yml`, `justfile`, `scripts/` (nếu có)
- Các cấu hình CI/CD để lấy các lệnh dựng/kiểm thử (build/test)
- `Dockerfile` để lấy thông tin về môi trường thực thi (runtime)

## Quét codebase (chung)
- Xác định thư mục gốc mã nguồn: `src/`, `lib/`, `app/`, `pkg/`, hoặc ngay tại thư mục gốc
- Các thư mục phân tầng (chỉ ghi nhận nếu có):
  `controllers`, `services`, `models`, `handlers`, `utils`, `config`
- Các điểm khởi chạy (entry points): `main.*`, `index.*`, `app.*`, `server.*`
- Vị trí lưu bài kiểm thử: `tests/`, `test/`, `spec/`, `__tests__/`, hoặc đặt cùng chỗ với mã nguồn (co-located)

## Đầu ra bắt buộc (CLAUDE.md chung)
Bao gồm những mục này nếu phát hiện thấy (liệt kê tên thực tế tìm được):
- **Điểm khởi chạy (Entry points)**: các tệp chính, kịch bản khởi động
- **Cấu trúc mã nguồn (Source structure)**: các thư mục cấp cao nhất bên dưới thư mục gốc mã nguồn
- **Tệp cấu hình (Config files)**: môi trường, thiết lập, mẫu tệp khóa bí mật (secrets template)
- **Hệ thống dựng (Build system)**: công cụ dựng được phát hiện và vị trí tệp cấu hình
- **Thiết lập kiểm thử (Test setup)**: framework kiểm thử và lệnh chạy kiểm thử

## Nguồn lấy lệnh thực thi
- Các mục cài đặt/sử dụng trong README
- Các đích (targets) trong `Makefile`, các tác vụ trong `Taskfile.yml`, các công thức (recipes) trong `justfile`
- Các bước trong luồng công việc CI (dựng, kiểm thử, kiểm tra mã nguồn - build, test, lint)
- Thư mục `scripts/`
- Chỉ đưa vào các lệnh thực sự có mặt trong kho lưu trữ

## Các đường dẫn chính cần đề cập (chỉ khi có mặt)
- Thư mục gốc mã nguồn và cấu trúc cấp cao nhất của nó
- Các tệp cấu hình/môi trường
- Thư mục kiểm thử
- Vị trí lưu tài liệu
- Thư mục chứa kết quả dựng (build output)
FILE:references/go.md
# Go

## Tín hiệu nhận diện
- `go.mod`, `go.sum`, `go.work`
- `cmd/`, `internal/`
- `main.go`
- `magefile.go`
- `Taskfile.yml`

## Tín hiệu đa mô-đun
- Tệp `go.work` chứa nhiều đường dẫn mô-đun
- Nhiều tệp `go.mod` nằm trong các thư mục con
- Các thư mục `apps/` hoặc `services/` mà mỗi thư mục con bên trong đều có tệp `go.mod` riêng

## Trước khi tạo, hãy phân tích các nguồn này
- `go.work`, `go.mod`, `go.sum`
- Bố cục các thư mục `cmd/`, `internal/`, `pkg/`
- `Makefile`, `Taskfile.yml`, `magefile.go` (nếu có)

## Quét codebase (đặc thù Go)
- Các thư mục gốc mã nguồn: `cmd/`, `internal/`, `pkg/`, `api/`
- Các thư mục phân tầng (chỉ ghi nhận nếu có):
  `handler`, `service`, `repository`, `store`, `config`
- Dấu hiệu nhận biết framework (chỉ ghi nhận nếu có):
  các lệnh import `gin`, `echo`, `fiber`, `chi`
- Các điểm khởi chạy (chỉ ghi nhận nếu có):
  `cmd/*/main.go`, `main.go`

## Đầu ra bắt buộc (CLAUDE.md cho mô-đun Go)
Bao gồm những mục này nếu phát hiện thấy (liệt kê tên thực tế tìm được):
- **Commands**: liệt kê các chương trình nhị phân (binaries) nằm dưới `cmd/`
- **Handlers**: liệt kê các gói xử lý HTTP (HTTP handler packages)
- **Services**: liệt kê các gói dịch vụ (service packages)
- **Repositories**: liệt kê các gói repository hoặc store
- **Models**: liệt kê các gói mô hình nghiệp vụ (domain model packages)
- **Config**: liệt kê các gói nạp cấu hình

## Nguồn lấy lệnh thực thi
- README/tài liệu hoặc cấu hình CI
- `Makefile`, `Taskfile.yml`, hoặc các kịch bản trong kho lưu trữ gọi công cụ Go
- Cách sử dụng `go test ./...`, `go run` trong tài liệu/kịch bản
- Chỉ đưa vào các lệnh thực sự có mặt trong kho lưu trữ

## Các đường dẫn chính cần đề cập (chỉ khi có mặt)
- `cmd/`, `internal/`, `pkg/`, `api/`
- Bố cục thư mục `tests/` hoặc các tệp `*_test.go`
FILE:references/ios.md
# iOS (Xcode/Swift)

## Tín hiệu nhận diện
- `Package.swift`
- `*.xcodeproj` hoặc `*.xcworkspace`
- `Podfile`, `Cartfile`
- `Project.swift`, `Tuist/`
- `fastlane/Fastfile`
- `*.xcconfig`
- `Sources/` hoặc `Tests/` (bố cục chuẩn SPM)

## Tín hiệu đa mô-đun
- Nhiều đích dựng (targets)/dự án bên trong `*.xcworkspace` hoặc `*.xcodeproj`
- Tệp `Package.swift` khai báo nhiều targets/products
- Bố cục thư mục `Sources/<TargetName>` và `Tests/<TargetName>`
- Tệp `Project.swift` định nghĩa nhiều targets (Tuist)

## Trước khi tạo, hãy phân tích các nguồn này
- `Package.swift` (SPM)
- `*.xcodeproj/project.pbxproj` hoặc `*.xcworkspace/contents.xcworkspacedata`
- `Podfile`, `Cartfile` (nếu có)
- `Project.swift` / `Tuist/` (nếu có)
- `fastlane/Fastfile` (nếu có)
- Bố cục `Sources/` và `Tests/` cho các targets

## Quét codebase (đặc thù iOS)
- Các thư mục gốc mã nguồn: `Sources/`, `Tests/`, `ios/` (nếu có)
- Các thư mục tính năng/phân tầng (chỉ ghi nhận nếu có):
  `Features/`, `Core/`, `Services/`, `Networking/`, `UI/`, `Domain/`, `Data/`
- Việc sử dụng SwiftUI (chỉ ghi nhận nếu có):
  `@main`, `App`, `@State`, `@StateObject`, `@ObservedObject`,
  `@Environment`, `@EnvironmentObject`, `@Binding`
- UIKit/vòng đời ứng dụng (chỉ ghi nhận nếu có):
  `UIApplicationDelegate`, `SceneDelegate`, `UIViewController`
- Combine/xử lý đồng thời (chỉ ghi nhận nếu có):
  `@Published`, `Publisher`, `AnyCancellable`, `@MainActor`, `Task`

## Đầu ra bắt buộc (CLAUDE.md cho mô-đun iOS)
Bao gồm những mục này nếu phát hiện thấy (liệt kê tên thực tế tìm được):
- **Danh mục tính năng (Features inventory)**: liệt kê các thư mục dưới `Features/` hoặc các target tính năng
- **Mô-đun cốt lõi (Core modules)**: liệt kê các thư mục dưới `Core/`, `Services/`, `Networking/`
- **Điều hướng (Navigation)**: liệt kê các coordinator, router, hoặc các tệp điều hướng SwiftUI
- **DI container**: liệt kê thiết lập tiêm phụ thuộc (Swinject, Factory, các container tự viết)
- **Tầng mạng (Network layer)**: liệt kê các trình khách API (API clients) hoặc dịch vụ kết nối mạng
- **Lưu trữ bền vững (Persistence)**: liệt kê các mô hình CoreData hoặc các lớp lưu trữ khác

## Nguồn lấy lệnh thực thi
- README/tài liệu hoặc cấu hình CI gọi bộ công cụ Xcode hoặc Swift
- Các kịch bản trong kho lưu trữ gọi tới công cụ Xcode/Swift
- Cách sử dụng `xcodebuild`, `swift build`, `swift test` trong tài liệu/kịch bản
- Chỉ đưa vào các lệnh thực sự có mặt trong kho lưu trữ

## Các đường dẫn chính cần đề cập (chỉ khi có mặt)
- `Sources/`, `Tests/`
- `fastlane/`
- `ios/` (đối với các kho lưu trữ React Native hoặc đa nền tảng)
FILE:references/java.md
# Java / JVM

## Tín hiệu nhận diện
- `pom.xml` hoặc `build.gradle*`
- `settings.gradle`, `gradle.properties`
- `mvnw`, `gradlew`
- `gradle/wrapper/gradle-wrapper.properties`
- `src/main/java`, `src/test/java`, `src/main/kotlin`
- `src/main/resources/application.yml`, `src/main/resources/application.properties`

## Tín hiệu đa mô-đun
- Tệp `settings.gradle*` bao gồm nhiều mô-đun
- Tệp `pom.xml` cha có thẻ `<modules>` (kiểu đóng gói `pom`)
- Nhiều tệp `build.gradle*` hoặc `pom.xml` nằm trong các thư mục con

## Trước khi tạo, hãy phân tích các nguồn này
- `settings.gradle*` và `build.gradle*` (nếu dùng Gradle)
- Tệp `pom.xml` cha và của từng mô-đun (nếu dùng Maven)
- `gradle/libs.versions.toml` (nếu có)
- `gradle.properties` / `mvnw` / `gradlew`
- `src/main/resources/application.yml|application.properties` (nếu có)

## Quét codebase (đặc thù Java/JVM)
- Các thư mục gốc mã nguồn: `src/main/java`, `src/main/kotlin`, `src/test/java`, `src/test/kotlin`
- Các thư mục gói/phân tầng (chỉ ghi nhận nếu có):
  `controller`, `service`, `repository`, `domain`, `model`, `dto`, `config`, `client`
- Các chú thích (annotations) của framework (chỉ ghi nhận nếu có):
  `@SpringBootApplication`, `@RestController`, `@Controller`, `@Service`,
  `@Repository`, `@Component`, `@Configuration`, `@Bean`, `@Transactional`
- Lưu trữ cơ sở dữ liệu/xác thực hợp lệ (chỉ ghi nhận nếu có):
  `@Entity`, `@Table`, `@Id`, `@OneToMany`, `@ManyToOne`, `@Valid`, `@NotNull`
- Các điểm khởi chạy (chỉ ghi nhận nếu có):
  các lớp `*Application` có hàm `main`

## Đầu ra bắt buộc (CLAUDE.md cho mô-đun Java/JVM)
Bao gồm những mục này nếu phát hiện thấy (liệt kê tên thực tế tìm được):
- **Controllers**: liệt kê các lớp gắn `@RestController` hoặc `@Controller`
- **Services**: liệt kê các lớp gắn `@Service`
- **Repositories**: liệt kê các lớp gắn `@Repository` hoặc các interface JPA
- **Entities**: liệt kê các lớp gắn `@Entity`
- **Cấu hình (Configuration)**: liệt kê các lớp gắn `@Configuration`
- **Bảo mật (Security)**: liệt kê cấu hình bảo mật hoặc các bộ lọc xác thực (auth filters)
- **Profiles**: liệt kê các Spring profile đang được sử dụng

## Nguồn lấy lệnh thực thi
- Các kịch bản trình bao bọc (wrapper scripts) của Maven/Gradle
- README/tài liệu hoặc cấu hình CI
- Cách sử dụng `./mvnw spring-boot:run`, `./gradlew bootRun` trong tài liệu/kịch bản
- Chỉ đưa vào các lệnh thực sự có mặt trong kho lưu trữ

## Các đường dẫn chính cần đề cập (chỉ khi có mặt)
- `src/main/java`, `src/test/java`
- `src/main/kotlin`, `src/test/kotlin`
- `src/main/resources`, `src/test/resources`
- `src/main/java/**/controller`, `src/main/java/**/service`, `src/main/java/**/repository`
FILE:references/node.md
# Bộ Công Cụ Node (Chung)

## Tín hiệu nhận diện
- `package.json`
- `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`
- `.nvmrc`, `.node-version`
- `tsconfig.json`
- `.npmrc`, `.yarnrc.yml`
- `next.config.*`, `nuxt.config.*`
- `nest-cli.json`, `svelte.config.*`, `astro.config.*`

## Tín hiệu đa mô-đun
- `pnpm-workspace.yaml`, `lerna.json`, `nx.json`, `turbo.json`, `rush.json`
- Tệp `package.json` ở thư mục gốc có khai báo `workspaces`
- Nhiều tệp `package.json` nằm dưới `apps/`, `packages/`

## Trước khi tạo, hãy phân tích các nguồn này
- Tệp `package.json` ở thư mục gốc và cấu hình workspace (`pnpm-workspace.yaml`, `lerna.json`,
  `nx.json`, `turbo.json`, `rush.json`)
- `apps/*/package.json`, `packages/*/package.json` (nếu là monorepo)
- `tsconfig.json` hoặc `jsconfig.json`
- Cấu hình framework: `next.config.*`, `nuxt.config.*`, `nest-cli.json`,
  `svelte.config.*`, `astro.config.*` (nếu có)

## Quét codebase (đặc thù Node)
- Các thư mục gốc mã nguồn: `src/`, `lib/`, `apps/`, `packages/`
- Các mẫu thư mục (chỉ ghi nhận nếu có):
  `routes`, `controllers`, `services`, `middlewares`, `handlers`,
  `utils`, `config`, `models`, `schemas`
- Dấu hiệu nhận biết framework (chỉ ghi nhận nếu có):
  Express (`express()`, `Router`), Koa (`new Koa()`),
  Fastify (`fastify()`), Nest (`@Controller`, `@Module`, `@Injectable`)
- Bố cục full-stack (chỉ ghi nhận nếu có):
  Next/Nuxt (`pages/`, `app/`, `server/`)

## Đầu ra bắt buộc (CLAUDE.md cho mô-đun Node)
Bao gồm những mục này nếu phát hiện thấy (liệt kê tên thực tế tìm được):
- **Routes/pages**: liệt kê các tệp định tuyến (route files) hoặc các component trang
- **Controllers/handlers**: liệt kê các tệp controller hoặc handler
- **Services**: liệt kê các lớp hoặc mô-đun dịch vụ
- **Middlewares**: liệt kê các tệp middleware
- **Models/schemas**: liệt kê các mô hình dữ liệu hoặc lược đồ xác thực (validation schemas)
- **Quản lý trạng thái (State management)**: liệt kê thiết lập kho trạng thái (Redux, Zustand, v.v.)
- **API clients**: liệt kê các mô-đun trình khách gọi API bên ngoài

## Nguồn lấy lệnh thực thi
- Các kịch bản (scripts) trong `package.json`
- README/tài liệu hoặc cấu hình CI
- Cách sử dụng kịch bản `npm|yarn|pnpm` trong tài liệu/scripts
- Chỉ đưa vào các lệnh thực sự có mặt trong kho lưu trữ

## Các đường dẫn chính cần đề cập (chỉ khi có mặt)
- `src/`, `lib/`
- `tests/`
- `apps/`, `packages/` (đối với monorepo)
- `pages/`, `app/`, `server/`, `api/`
- `controllers/`, `services/`
FILE:references/php.md
# PHP

## Tín hiệu nhận diện
- `composer.json`, `composer.lock`
- `public/index.php`
- `artisan`, `spark`, `bin/console` (các điểm khởi chạy của framework)
- `phpunit.xml`, `phpstan.neon`, `phpstan.neon.dist`, `psalm.xml`
- `config/app.php`
- `routes/web.php`, `routes/api.php`
- `config/packages/` (Symfony)
- `app/Config/` (CI4)
- `ext-phalcon` trong composer.json (Phalcon)
- `phalcon/ide-stubs`, `phalcon/devtools` (Phalcon)

## Tín hiệu đa mô-đun
- `modules/` hoặc `app/Modules/` (kiến trúc kiểu HMVC)
- `app/Config/Modules.php`, `app/Config/Autoload.php` (CI4)
- Nhiều đường dẫn gốc PSR-4 trong `composer.json`
- Nhiều tệp `composer.json` nằm dưới `packages/` hoặc `apps/`
- Thư mục `apps/` có các thư mục con chứa `Module.php` hoặc `controllers/`

## Trước khi tạo, hãy phân tích các nguồn này
- `composer.json`, `composer.lock`
- `config/` và `routes/` (cấu hình của framework)
- `app/Config/*` (CI4)
- `modules/` hoặc `app/Modules/` (nếu theo mô hình HMVC)
- `phpunit.xml`, `phpstan.neon*`, `psalm.xml` (nếu có)
- `bin/worker.php`, `bin/console.php` (các điểm khởi chạy giao diện dòng lệnh CLI)

## Quét codebase (đặc thù PHP)
- Các thư mục gốc mã nguồn: `app/`, `src/`, `modules/`, `packages/`, `apps/`
- Cấu trúc Laravel (chỉ ghi nhận nếu có):
  `app/Http/Controllers`, `app/Models`, `database/migrations`,
  `routes/*.php`, `resources/views`
- Cấu trúc Symfony (chỉ ghi nhận nếu có):
  `src/Controller`, `src/Entity`, `config/packages`, `templates`
- Cấu trúc CodeIgniter (chỉ ghi nhận nếu có):
  `app/Controllers`, `app/Models`, `app/Views`, `app/Config/Routes.php`,
  `app/Database/Migrations`
- Cấu trúc Phalcon (chỉ ghi nhận nếu có):
  `apps/*/controllers/`, `apps/*/Module.php`, `models/`
- Các thuộc tính/chú thích (attributes/annotations - chỉ ghi nhận nếu có):
  `#[Route]`, `#[Entity]`, `#[ORM\\Column]`

## Khám phá mô-đun nghiệp vụ (Business module discovery)
Quét các đường dẫn sau dựa trên framework được phát hiện:
- Laravel: `app/Services/`, `app/Domains/`, `app/Modules/`, `packages/`
- Symfony: các thư mục cấp cao nhất bên dưới `src/`
- CodeIgniter: `app/Modules/`, `modules/`
- Phalcon: `src/`, `apps/*/`
- Chung (Generic): `src/`, `lib/`

Đối với mỗi đường dẫn:
- Liệt kê 5-10 mô-đun lớn nhất tính theo số lượng tệp
- Đối với mỗi mô-đun quan trọng (>5 tệp), ghi chú lại mục đích của nó nếu có thể suy luận được từ tên gọi
- Xác định các mẫu phân tầng nếu có: `*/Repository/`, `*/Service/`, `*/Controller/`, `*/Action/`

## Tín hiệu tạo CLAUDE.md ở cấp độ mô-đun
Quét các đường dẫn sau để tìm những mô-đun quan trọng (đặc thù theo từng framework):
- `src/` - Symfony, Phalcon, các framework tự xây dựng
- `app/Services/`, `app/Domains/` - Laravel hướng miền nghiệp vụ (domain-driven)
- `app/Modules/`, `modules/` - Laravel/CI4 theo mô hình HMVC
- `packages/` - các gói nội bộ của Laravel
- `apps/` - đa ứng dụng trên Phalcon

Tạo tệp `<path>/<Module>/CLAUDE.md` khi:
- Đạt ngưỡng: mô-đun có >5 tệp HOẶC có tệp `README.md` riêng
- Bỏ qua các thư mục tiện ích: `Helper/`, `Exception/`, `Trait/`, `Contract/`, `Interface/`, `Constants/`, `Support/`
- Không bắt buộc phải có cấu trúc phân tầng; vẫn cung cấp thông tin mô-đun bất kể kiến trúc cụ thể

### Nội dung CLAUDE.md của mô-đun (tối đa 120 dòng)
- Mục đích (Purpose): mô tả mô-đun trong 1-2 câu
- Cấu trúc (Structure): liệt kê các thư mục con (Service/, Repository/, v.v.)
- Các lớp chính (Key classes): các lớp service/manager/action chính
- Phụ thuộc (Dependencies): các mô-đun khác mà mô-đun này phụ thuộc vào (thông qua các câu lệnh `use`)
- Điểm giao tiếp (Entry points): các interface/facade công khai chính
- Đặc thù theo framework: ServiceProvider (Laravel), Module.php (Phalcon/CI4)

## Nhận diện Worker/Job
- `bin/worker.php` hoặc các điểm khởi chạy worker tương tự
- Các thư mục `*/Job/`, `*/Jobs/`, `*/Worker/`
- Các tệp cấu hình hàng đợi (`queue.php`, `rabbitmq.php`, `amqp.php`)
- Liệt kê các lớp job nếu có

## Nhận diện phân tách phiên bản API (API versioning)
- Các mẫu `routes_v*.php` hoặc `routes/v*/`
- Cấu trúc thư mục `controllers/v*/`
- Ghi chú lại phiên bản API hiện tại/đang hoạt động dựa vào các tệp định tuyến (route files) hoặc cấu hình

## Đầu ra bắt buộc (CLAUDE.md cho mô-đun PHP)
Bao gồm những mục này nếu phát hiện thấy (liệt kê tên thực tế tìm được):
- **Controllers**: liệt kê các thư mục/lớp controller
- **Models**: liệt kê các lớp hoặc thư mục chứa model/entity
- **Services**: liệt kê các lớp hoặc thư mục chứa service
- **Repositories**: liệt kê các lớp hoặc thư mục chứa repository
- **Routes**: liệt kê các tệp định tuyến và mẫu đánh số phiên bản
- **Migrations**: đề cập đến thư mục migrations và tổng số lượng tệp
- **Middleware**: liệt kê các lớp middleware
- **Views/templates**: đề cập đến bộ máy hiển thị giao diện (view engine) và bố cục
- **Workers/Jobs**: liệt kê các lớp job nếu có
- **Mô-đun nghiệp vụ (Business modules)**: liệt kê các mô-đun hàng đầu từ các đường dẫn mã nguồn phát hiện được theo quy mô

## Nguồn lấy lệnh thực thi
- Các kịch bản trong `composer.json`
- README/tài liệu hoặc cấu hình CI
- Cách sử dụng `php artisan`, `bin/console` trong tài liệu/kịch bản
- Các lệnh chạy `bin/worker.php`
- Chỉ đưa vào các lệnh thực sự có mặt trong kho lưu trữ

## Các đường dẫn chính cần đề cập (chỉ khi có mặt)
- `app/`, `src/`, `apps/`
- `public/`, `routes/`, `config/`, `database/`
- `app/Http/`, `resources/`, `storage/` (Laravel)
- `templates/` (Symfony)
- `app/Controllers/`, `app/Views/` (CI4)
- `apps/*/controllers/`, `models/` (Phalcon)
- `tests/`, `tests/acceptance/`, `tests/unit/`
FILE:references/python.md
# Python

## Tín hiệu nhận diện
- `pyproject.toml`
- `requirements.txt`, `requirements-dev.txt`, `Pipfile`, `poetry.lock`
- `tox.ini`, `pytest.ini`
- `manage.py`
- `setup.py`, `setup.cfg`
- `settings.py`, `urls.py` (Django)

## Tín hiệu đa mô-đun
- Nhiều tệp `pyproject.toml`/`setup.py`/`setup.cfg` nằm trong các thư mục con
- Các thư mục `packages/` hoặc `apps/` mà mỗi thư mục con đều có cấu hình gói riêng
- Thư mục `apps/` kiểu Django chứa nhiều tệp `apps.py` (nếu có)

## Trước khi tạo, hãy phân tích các nguồn này
- `pyproject.toml` hoặc `setup.py` / `setup.cfg`
- `requirements*.txt`, `Pipfile`, `poetry.lock`
- `tox.ini`, `pytest.ini`
- `manage.py`, `settings.py`, `urls.py` (nếu là Django)
- Các thư mục gốc của gói nằm dưới `src/`, `app/`, `packages/` (nếu có)

## Quét codebase (đặc thù Python)
- Các thư mục gốc mã nguồn: `src/`, `app/`, `packages/`, `tests/`
- Các mẫu thư mục (chỉ ghi nhận nếu có):
  `api`, `routers`, `views`, `services`, `repositories`,
  `models`, `schemas`, `utils`, `config`
- Cấu trúc Django (chỉ ghi nhận nếu có):
  `apps.py`, `models.py`, `views.py`, `urls.py`, `migrations/`, `settings.py`
- Dấu hiệu nhận biết FastAPI/Flask (chỉ ghi nhận nếu có):
  `FastAPI()`, `APIRouter`, `@app.get`, `@router.post`,
  `Flask(__name__)`, `Blueprint`
- Việc sử dụng mô hình kiểu dữ liệu (chỉ ghi nhận nếu có):
  `pydantic.BaseModel`, `TypedDict`, `dataclass`

## Đầu ra bắt buộc (CLAUDE.md cho mô-đun Python)
Bao gồm những mục này nếu phát hiện thấy (liệt kê tên thực tế tìm được):
- **Routers/views**: liệt kê các tệp định tuyến API hoặc tệp view
- **Services**: liệt kê các mô-đun dịch vụ (service modules)
- **Models/schemas**: liệt kê các mô hình dữ liệu (Pydantic, SQLAlchemy, Django)
- **Repositories**: liệt kê các mô-đun repository hoặc DAO
- **Migrations**: đề cập đến thư mục chứa migrations
- **Middleware**: liệt kê các lớp middleware
- **Django apps**: liệt kê các ứng dụng đã cài đặt (nếu dùng Django)

## Nguồn lấy lệnh thực thi
- Các mục cấu hình công cụ (`tool`) trong `pyproject.toml`
- README/tài liệu hoặc cấu hình CI
- Các kịch bản trong kho lưu trữ gọi tới bộ công cụ Python
- Cách sử dụng `python manage.py`, `pytest`, `tox` trong tài liệu/kịch bản
- Chỉ đưa vào các lệnh thực sự có mặt trong kho lưu trữ

## Các đường dẫn chính cần đề cập (chỉ khi có mặt)
- `src/`, `app/`, `scripts/`
- `templates/`, `static/`
- `tests/`
FILE:references/react-native.md
# React Native

## Tín hiệu nhận diện
- Tệp `package.json` có chứa `react-native`
- `react-native.config.js`
- `metro.config.js`
- `ios/`, `android/`
- `babel.config.js`, `app.json`, `app.config.*`
- `eas.json`, có gói `expo` trong `package.json`

## Tín hiệu đa mô-đun
- `pnpm-workspace.yaml`, `lerna.json`, `nx.json`, `turbo.json`
- Tệp `package.json` ở thư mục gốc có khai báo `workspaces`
- Các thư mục `packages/` hoặc `apps/` mà mỗi thư mục con đều có `package.json`

## Trước khi tạo, hãy phân tích các nguồn này
- Tệp `package.json` ở thư mục gốc và cấu hình workspace (`pnpm-workspace.yaml`, `lerna.json`,
  `nx.json`, `turbo.json`)
- `react-native.config.js`, `metro.config.js`
- Các thư mục mã gốc (native folders) `ios/` và `android/`
- `app.json` / `app.config.*` / `eas.json` (nếu dùng Expo)

## Quét codebase (đặc thù React Native)
- Các thư mục gốc mã nguồn: `src/`, `app/`
- Các điểm khởi chạy (chỉ ghi nhận nếu có):
  `index.js`, `index.ts`, `App.tsx`
- Các thư mục native (chỉ ghi nhận nếu có): `ios/`, `android/`
- Điều hướng/quản lý trạng thái (chỉ ghi nhận nếu có):
  `react-navigation`, `redux`, `mobx`
- Các mẫu mô-đun native (chỉ ghi nhận nếu có):
  `NativeModules`, `TurboModule`

## Đầu ra bắt buộc (CLAUDE.md cho mô-đun React Native)
Bao gồm những mục này nếu phát hiện thấy (liệt kê tên thực tế tìm được):
- **Screens/navigators**: liệt kê các component màn hình và bộ điều hướng (navigators)
- **Components**: liệt kê các thư mục chứa component dùng chung
- **Services/API**: liệt kê các mô-đun trình khách gọi API
- **Quản lý trạng thái (State management)**: liệt kê thiết lập kho trạng thái (store)
- **Native modules**: liệt kê các mô-đun native tùy chỉnh
- **Thư mục nền tảng (Platform folders)**: đề cập đến thiết lập trong ios/ và android/

## Nguồn lấy lệnh thực thi
- Các kịch bản (scripts) trong `package.json`
- README/tài liệu hoặc cấu hình CI
- Các tệp cấu hình dựng native trong `ios/` và `android/`
- Cách sử dụng kịch bản `expo` trong tài liệu/scripts (nếu dùng Expo)
- Chỉ đưa vào các lệnh thực sự có mặt trong kho lưu trữ

## Các đường dẫn chính cần đề cập (chỉ khi có mặt)
- `ios/`, `android/`
- `src/`, `app/`
FILE:references/react-web.md
# React (Web)

## Tín hiệu nhận diện
- `package.json`
- `src/`, `public/`
- `vite.config.*`, `next.config.*`, `webpack.config.*`
- `tsconfig.json`
- `turbo.json`
- `app/` hoặc `pages/` (Next.js)

## Tín hiệu đa mô-đun
- `pnpm-workspace.yaml`, `lerna.json`, `nx.json`, `turbo.json`
- Tệp `package.json` ở thư mục gốc có khai báo `workspaces`
- Các thư mục `apps/` và `packages/` mà mỗi thư mục con đều có `package.json`

## Trước khi tạo, hãy phân tích các nguồn này
- Tệp `package.json` ở thư mục gốc và cấu hình workspace (`pnpm-workspace.yaml`, `lerna.json`,
  `nx.json`, `turbo.json`)
- `apps/*/package.json`, `packages/*/package.json` (nếu là monorepo)
- `vite.config.*`, `next.config.*`, `webpack.config.*`
- `tsconfig.json` / `jsconfig.json`

## Quét codebase (đặc thù React web)
- Các thư mục gốc mã nguồn: `src/`, `app/`, `pages/`, `components/`, `hooks/`, `services/`
- Các mẫu thư mục (chỉ ghi nhận nếu có):
  `routes`, `store`, `state`, `api`, `utils`, `assets`
- Dấu hiệu định tuyến (chỉ ghi nhận nếu có):
  React Router (`Routes`, `Route`), Next (`app/`, `pages/`)
- Quản lý trạng thái (chỉ ghi nhận nếu có):
  `redux`, `zustand`, `recoil`
- Quy ước đặt tên (chỉ ghi nhận nếu có):
  các hook bắt đầu bằng `use*`, các component viết theo kiểu PascalCase

## Đầu ra bắt buộc (CLAUDE.md cho mô-đun React web)
Bao gồm những mục này nếu phát hiện thấy (liệt kê tên thực tế tìm được):
- **Pages/routes**: liệt kê các component trang hoặc tệp định tuyến
- **Components**: liệt kê các thư mục chứa component dùng chung
- **Hooks**: liệt kê các hook tùy chỉnh (custom hooks)
- **Services/API**: liệt kê các mô-đun trình khách gọi API
- **Quản lý trạng thái (State management)**: liệt kê thiết lập kho trạng thái (Redux, Zustand, v.v.)
- **Utils**: liệt kê các mô-đun tiện ích

## Nguồn lấy lệnh thực thi
- Các kịch bản trong `package.json`
- README/tài liệu hoặc cấu hình CI
- Chỉ đưa vào các lệnh thực sự có mặt trong kho lưu trữ

## Các đường dẫn chính cần đề cập (chỉ khi có mặt)
- `src/`, `public/`
- `app/`, `pages/`, `components/`
- `hooks/`, `services/`
- `apps/`, `packages/` (đối với monorepo)
FILE:references/ruby.md
# Ruby / Rails

## Tín hiệu nhận diện
- `Gemfile`, `Gemfile.lock`
- `Rakefile`
- `config.ru`
- `bin/rails` hoặc `bin/rake`
- `config/application.rb`
- `config/routes.rb`

## Tín hiệu đa mô-đun
- Nhiều tệp `Gemfile` hoặc `.gemspec` nằm trong các thư mục con
- Các thư mục `gems/`, `packages/`, hoặc `engines/` có các đặc tả gem riêng biệt
- Nhiều ứng dụng Rails nằm dưới `apps/` (mỗi ứng dụng đều có `config/application.rb`)

## Trước khi tạo, hãy phân tích các nguồn này
- `Gemfile`, `Gemfile.lock`, và bất kỳ tệp `.gemspec` nào
- `config/application.rb`, `config/routes.rb`
- `Rakefile` / `bin/rails` (nếu có)
- `engines/`, `gems/`, `apps/` (nếu là thiết lập đa ứng dụng/engine)

## Quét codebase (đặc thù Ruby/Rails)
- Các thư mục gốc mã nguồn: `app/`, `lib/`, `engines/`, `gems/`
- Các tầng của Rails (chỉ ghi nhận nếu có):
  `app/models`, `app/controllers`, `app/views`, `app/jobs`, `app/services`
- Cấu hình và bộ khởi tạo (chỉ ghi nhận nếu có):
  `config/routes.rb`, `config/application.rb`, `config/initializers/`
- ActiveRecord/migrations (chỉ ghi nhận nếu có):
  `db/migrate`, `ActiveRecord::Base`
- Kiểm thử (chỉ ghi nhận nếu có): `spec/`, `test/`

## Đầu ra bắt buộc (CLAUDE.md cho mô-đun Ruby)
Bao gồm những mục này nếu phát hiện thấy (liệt kê tên thực tế tìm được):
- **Controllers**: liệt kê các lớp controller
- **Models**: liệt kê các mô hình ActiveRecord
- **Services**: liệt kê các đối tượng dịch vụ (service objects)
- **Jobs**: liệt kê các lớp xử lý tác vụ chạy ngầm (background job classes)
- **Routes**: tóm tắt các không gian tên định tuyến (route namespaces) chính
- **Migrations**: đề cập đến số lượng tệp trong db/migrate
- **Engines**: liệt kê các engine được gắn kết (nếu có)

## Nguồn lấy lệnh thực thi
- README/tài liệu hoặc cấu hình CI gọi `bundle`, `rails`, `rake`
- Các tác vụ trong `Rakefile`
- Cách sử dụng `bundle exec` trong tài liệu/kịch bản
- Chỉ đưa vào các lệnh thực sự có mặt trong kho lưu trữ

## Các đường dẫn chính cần đề cập (chỉ khi có mặt)
- `app/`, `config/`, `db/`
- `app/controllers/`, `app/models/`, `app/views/`
- `spec/` hoặc `test/`
FILE:references/rust.md
# Rust

## Tín hiệu nhận diện
- `Cargo.toml`, `Cargo.lock`
- `rust-toolchain.toml`
- `src/main.rs`, `src/lib.rs`
- Các thành viên không gian làm việc (workspace members) trong `Cargo.toml`, thư mục `crates/`

## Tín hiệu đa mô-đun
- Mục `[workspace]` có khai báo `members` trong `Cargo.toml`
- Nhiều tệp `Cargo.toml` nằm dưới `crates/` hoặc `apps/`

## Trước khi tạo, hãy phân tích các nguồn này
- Tệp `Cargo.toml`, `Cargo.lock` ở thư mục gốc
- `rust-toolchain.toml` (nếu có)
- Các tệp `Cargo.toml` thành viên của workspace trong `crates/` hoặc `apps/`
- `src/main.rs` / `src/lib.rs`

## Quét codebase (đặc thù Rust)
- Các thư mục gốc mã nguồn: `src/`, `crates/`, `tests/`, `examples/`
- Bố cục mô-đun (chỉ ghi nhận nếu có):
  `lib.rs`, `main.rs`, `mod.rs`, `src/bin/*`
- Việc sử dụng Serde (chỉ ghi nhận nếu có):
  `#[derive(Serialize, Deserialize)]`
- Bất đồng bộ/môi trường thực thi (chỉ ghi nhận nếu có):
  `tokio`, `async-std`
- Các web framework (chỉ ghi nhận nếu có):
  `axum`, `actix-web`, `warp`

## Đầu ra bắt buộc (CLAUDE.md cho mô-đun Rust)
Bao gồm những mục này nếu phát hiện thấy (liệt kê tên thực tế tìm được):
- **Crates**: liệt kê các crate trong workspace kèm theo mục đích sử dụng
- **Binaries**: liệt kê các tệp trong `src/bin/*` hoặc các đích dựng `[[bin]]`
- **Modules**: liệt kê các khai báo `mod` ở cấp cao nhất
- **Handlers/routes**: liệt kê các mô-đun xử lý web (nếu là ứng dụng web)
- **Models**: liệt kê các mô-đun mô hình nghiệp vụ (domain models)
- **Config**: liệt kê các mô-đun nạp cấu hình

## Nguồn lấy lệnh thực thi
- README/tài liệu hoặc cấu hình CI
- Các kịch bản trong kho lưu trữ gọi lệnh `cargo`
- Cách sử dụng `cargo test`, `cargo run` trong tài liệu/kịch bản
- Chỉ đưa vào các lệnh thực sự có mặt trong kho lưu trữ

## Các đường dẫn chính cần đề cập (chỉ khi có mặt)
- `src/`, `crates/`
- `tests/`, `examples/`, `benches/`

Claude Agent Infrastructure+2

B@barisatalay

skill-master

Kỹ năng

Phân tích các mẫu kiến trúc trong mã nguồn (codebase patterns) để phát hiện các kỹ năng còn thiếu và tạo mới/cập nhật các tệp SKILL.md trong .claude/skills/ với các ví dụ thực tế được trích xuất trực tiếp từ repo.

---
name: skill-master
description: Phát hiện các mẫu kiến trúc trong mã nguồn và tự động tạo các tệp SKILL cho .claude/skills/. Sử dụng khi phân tích dự án để tìm các kỹ năng còn thiếu, tạo kỹ năng mới từ các mẫu mã nguồn hoặc đồng bộ hóa kỹ năng với cấu trúc dự án.
version: 1.0.0
---

# Skill Master

## Tổng quan

Phân tích mã nguồn (codebase) để phát hiện các mẫu kiến trúc (patterns) và tạo mới/cập nhật các tệp SKILL trong `.claude/skills/`. Hỗ trợ các dự án đa nền tảng với khả năng nhận diện mẫu đặc thù theo từng ngăn xếp công nghệ (stack-specific).

**Khả năng:**
- Quét mã nguồn để tìm các mẫu kiến trúc (ViewModel, Repository, Room, v.v.)
- So sánh các mẫu phát hiện được với các kỹ năng hiện có
- Tự động tạo các tệp SKILL kèm ví dụ mã nguồn thực tế
- Theo dõi phiên bản và cập nhật thông minh

## Cách AI phát hiện và sử dụng kỹ năng này

Kỹ năng này được kích hoạt khi người dùng:
- Yêu cầu phân tích dự án để tìm các kỹ năng còn thiếu
- Yêu cầu tạo kỹ năng từ các mẫu trong mã nguồn
- Muốn đồng bộ hóa hoặc cập nhật các kỹ năng hiện có
- Đề cập đến "skill discovery", "generate skills", hoặc "skill-sync"

**Tín hiệu nhận diện:**
- Sự hiện diện của thư mục `.claude/skills/`
- Cấu trúc dự án khớp với các mẫu đã biết
- Các tệp biên dịch/cấu hình chỉ rõ nền tảng công nghệ (xem phần tài liệu tham khảo)

## Các Chế độ Hoạt động (Modes)

### Chế độ Khám phá (Discover Mode)

Phân tích mã nguồn và báo cáo các kỹ năng còn thiếu.

**Các bước:**
1. Nhận diện nền tảng thông qua các tệp biên dịch/cấu hình (xem tài liệu tham khảo)
2. Quét các thư mục mã nguồn gốc để tìm các dấu hiệu nhận biết mẫu (pattern indicators)
3. So sánh các mẫu phát hiện được với thư mục `.claude/skills/` hiện có
4. Xuất báo cáo phân tích khoảng trống thiếu hụt (gap analysis report)

**Định dạng đầu ra:**
```
Các Mẫu Phát hiện được (Detected Patterns): {count}
| Mẫu (Pattern) | Số Tệp Tìm thấy | Vị trí Ví dụ |
|---------|-------------|------------------|
| {name}  | {count}     | {path}           |

Kỹ năng Hiện có (Existing Skills): {count}
Kỹ năng Còn thiếu (Missing Skills): {count}
- {skill-name}: {pattern}, tìm thấy {file-count} tệp
```

### Chế độ Tạo mới (Generate Mode)

Tạo các tệp SKILL từ những mẫu đã phát hiện.

**Các bước:**
1. Chạy bước khám phá để xác định các kỹ năng còn thiếu
2. Đối với mỗi kỹ năng còn thiếu:
   - Tìm 2-3 tệp mã nguồn đại diện
   - Trích xuất: các câu lệnh import, chú thích (annotations), cấu trúc lớp, quy ước đặt tên
   - Trích xuất các quy tắc từ `.ruler/*.md` nếu có
3. Tạo tệp SKILL.md sử dụng cấu trúc khuôn mẫu (template)
4. Thêm thông tin phiên bản và dấu đánh dấu nguồn (source marker)

**Cấu trúc SKILL được tạo:**
```yaml
---
name: {pattern-name}
description: {Generated description with trigger keywords}
version: 1.0.0
---

# {Title}

## Overview
{Brief description from pattern analysis}

## File Structure
{Extracted from codebase}

## Implementation Pattern
{Real code examples - anonymized}

## Rules
### Do
{From .ruler/*.md + codebase conventions}

### Don't
{Anti-patterns found}

## File Location
{Actual paths from codebase}
```

## Chiến lược Tạo mới (Create Strategy)

Khi tệp SKILL mục tiêu chưa tồn tại:
1. Tạo tệp mới bằng khuôn mẫu (template)
2. Đặt `version: 1.0.0` trong phần frontmatter
3. Đưa vào đầy đủ tất cả các phần bắt buộc
4. Thêm dấu đánh dấu nguồn ở cuối tệp (xem Định dạng Dấu đánh dấu)

## Chiến lược Cập nhật (Update Strategy)

**Kiểm tra dấu đánh dấu (Marker check):** Tìm dòng `<!-- Generated by skill-master command` ở cuối tệp.

**Nếu có dấu đánh dấu (lần chạy tiếp theo):**
- Hợp nhất thông minh (Smart merge): giữ nguyên nội dung tùy chỉnh của người dùng, bổ sung các phần còn thiếu
- Tăng số phiên bản: major (thay đổi lớn không tương thích) / minor (thêm tính năng) / patch (sửa lỗi nhỏ)
- Cập nhật danh sách tệp nguồn trong dấu đánh dấu

**Nếu không có dấu đánh dấu (lần chạy đầu tiên trên tệp đã tồn tại):**
- Sao lưu: `SKILL.md` → `SKILL.md.bak`
- Sử dụng bản sao lưu làm nguồn, trích xuất nội dung liên quan
- Tạo tệp mới hoàn chỉnh kèm theo dấu đánh dấu
- Đặt `version: 1.0.0`

## Định dạng Dấu đánh dấu (Marker Format)

Đặt ở CUỐI tệp SKILL.md được tạo ra:

```html
<!-- Generated by skill-master command
Version: {version}
Sources:
- path/to/source1.kt
- path/to/source2.md
- .ruler/rule-file.md
Last updated: {YYYY-MM-DD}
-->
```

## Tài liệu Tham khảo theo Nền tảng (Platform References)

Đọc tài liệu tham khảo tương ứng khi phát hiện nền tảng:

| Nền tảng | Tệp Nhận diện | Tài liệu Tham khảo |
|----------|-----------------|-----------|
| Android/Gradle | `build.gradle`, `settings.gradle` | `references/android.md` |
| iOS/Xcode | `*.xcodeproj`, `Package.swift` | `references/ios.md` |
| React (web) | `package.json` + react | `references/react-web.md` |
| React Native | `package.json` + react-native | `references/react-native.md` |
| Flutter/Dart | `pubspec.yaml` | `references/flutter.md` |
| Node.js | `package.json` | `references/node.md` |
| Python | `pyproject.toml`, `requirements.txt` | `references/python.md` |
| Java/JVM | `pom.xml`, `build.gradle` | `references/java.md` |
| .NET/C# | `*.csproj`, `*.sln` | `references/dotnet.md` |
| Go | `go.mod` | `references/go.md` |
| Rust | `Cargo.toml` | `references/rust.md` |
| PHP | `composer.json` | `references/php.md` |
| Ruby | `Gemfile` | `references/ruby.md` |
| Elixir | `mix.exs` | `references/elixir.md` |
| C/C++ | `CMakeLists.txt`, `Makefile` | `references/cpp.md` |
| Không xác định (Unknown) | - | `references/generic.md` |

Nếu phát hiện nhiều nền tảng cùng lúc, hãy đọc nhiều tài liệu tham khảo tương ứng.

## Quy tắc

### Nên làm (Do)
- Chỉ trích xuất các mẫu đã được xác minh thực tế trong mã nguồn
- Sử dụng các ví dụ mã nguồn thực tế (ẩn danh hóa logic nghiệp vụ)
- Đưa các từ khóa kích hoạt (trigger keywords) vào phần mô tả (description)
- Giữ cho tệp SKILL.md dưới 500 dòng
- Tham chiếu đến các tệp bên ngoài cho phần nội dung chi tiết
- Bảo toàn các phần tùy chỉnh riêng trong quá trình cập nhật
- Luôn tạo bản sao lưu trước khi sửa đổi lần đầu tiên

### Không nên làm (Don't)
- Đưa vào các thông tin bí mật (secrets), token hoặc thông tin xác thực (credentials)
- Đưa vào các chi tiết logic đặc thù của nghiệp vụ kinh doanh
- Tạo các placeholder giữ chỗ mà không có nội dung thực tế
- Ghi đè lên các tùy chỉnh của người dùng mà không sao lưu
- Tạo chuỗi tham chiếu quá sâu (tối đa 1 cấp)
- Ghi tệp ra bên ngoài thư mục `.claude/skills/`

## Quy tắc Trích xuất Nội dung

**Từ mã nguồn (codebase):**
- Trích xuất: cấu trúc lớp (class structures), chú thích (annotations), mẫu import, vị trí tệp, quy ước đặt tên
- Không bao giờ trích xuất: các giá trị gán cứng (hardcoded values), bí mật (secrets), khóa API (API keys), thông tin định danh cá nhân (PII)

**Từ .ruler/*.md (nếu có):**
- Trích xuất: các quy tắc Nên làm/Không nên làm (Do/Don't), các ràng buộc kiến trúc, quy tắc phụ thuộc (dependency rules)

## Báo cáo Đầu ra (Output Report)

Sau khi tạo xong, hãy in ra:
```
SKILL GENERATION REPORT

Skills Generated: {count}

{skill-name} [CREATED | UPDATED | BACKED_UP+CREATED]
├── Analyzed: {file-count} source files
├── Sources: {list of source files}
├── Rules from: {.ruler files if any}
└── Output: .claude/skills/{skill-name}/SKILL.md ({line-count} lines)

Validation:
✓ YAML frontmatter valid
✓ Description includes trigger keywords
✓ Content under 500 lines
✓ Has required sections
```

## Ràng buộc An toàn (Safety Constraints)

- Không bao giờ ghi tệp ra bên ngoài `.claude/skills/`
- Không bao giờ xóa nội dung mà không có bản sao lưu
- Luôn sao lưu trước khi sửa đổi lần đầu tiên
- Bảo toàn các tùy chỉnh của người dùng
- Mang tính tất định (Deterministic): cùng đầu vào → cùng đầu ra
FILE:references/android.md
# Android (Gradle/Kotlin)

## Tín hiệu nhận diện
- `settings.gradle` hoặc `settings.gradle.kts`
- `build.gradle` hoặc `build.gradle.kts`
- `gradle.properties`, `gradle/libs.versions.toml`
- `gradlew`, `gradle/wrapper/gradle-wrapper.properties`
- `app/src/main/AndroidManifest.xml`

## Tín hiệu đa mô-đun (Multi-module signals)
- Có nhiều lệnh `include(...)` trong `settings.gradle*`
- Có nhiều thư mục chứa `build.gradle*` + `src/`
- Các thư mục gốc phổ biến: `feature/`, `core/`, `library/`, `domain/`, `data/`

## Các nguồn kiểm tra trước khi tạo (Pre-generation sources)
- `settings.gradle*` (danh sách mô-đun)
- `build.gradle*` (thư mục gốc + các mô-đun)
- `gradle/libs.versions.toml` (các thư viện phụ thuộc - dependencies)
- `config/detekt/detekt.yml` (nếu có)
- `**/AndroidManifest.xml`

## Các mẫu quét mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `*/src/main/java/`, `*/src/main/kotlin/`

### Các mẫu phân tầng/thư mục (ghi nhận nếu có)
`features/`, `core/`, `common/`, `data/`, `domain/`, `presentation/`, `ui/`, `di/`, `navigation/`, `network/`

### Các dấu hiệu nhận biết mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Nhận diện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| ViewModel | `@HiltViewModel`, `ViewModel()`, `MVI<` | viewmodel-mvi |
| Repository | `*Repository`, `*RepositoryImpl` | data-repository |
| UseCase | `operator fun invoke`, `*UseCase` | domain-usecase |
| Room Entity | `@Entity`, `@PrimaryKey`, `@ColumnInfo` | room-entity |
| Room DAO | `@Dao`, `@Query`, `@Insert`, `@Update` | room-dao |
| Migration | `Migration(`, `@Database(version=` | room-migration |
| Type Converter | `@TypeConverter`, `@TypeConverters` | type-converter |
| DTO | `@SerializedName`, `*Request`, `*Response` | network-dto |
| Compose Screen | `@Composable`, `NavGraphBuilder.` | compose-screen |
| Bottom Sheet | `ModalBottomSheet`, `*BottomSheet(` | bottomsheet-screen |
| Navigation | `@Route`, `NavGraphBuilder.`, `composable(` | navigation-route |
| Hilt Module | `@Module`, `@Provides`, `@Binds`, `@InstallIn` | hilt-module |
| Worker | `@HiltWorker`, `CoroutineWorker`, `WorkManager` | worker-task |
| DataStore | `DataStore<Preferences>`, `preferencesDataStore` | datastore-preference |
| Retrofit API | `@GET`, `@POST`, `@PUT`, `@DELETE` | retrofit-api |
| Mapper | `*.toModel()`, `*.toEntity()`, `*.toDto()` | data-mapper |
| Interceptor | `Interceptor`, `intercept()` | network-interceptor |
| Paging | `PagingSource`, `Pager(`, `PagingData` | paging-source |
| Broadcast Receiver | `BroadcastReceiver`, `onReceive(` | broadcast-receiver |
| Android Service | `: Service()`, `ForegroundService` | android-service |
| Notification | `NotificationCompat`, `NotificationChannel` | notification-builder |
| Analytics | `FirebaseAnalytics`, `logEvent` | analytics-event |
| Feature Flag | `RemoteConfig`, `FeatureFlag` | feature-flag |
| App Widget | `AppWidgetProvider`, `GlanceAppWidget` | app-widget |
| Unit Test | `@Test`, `MockK`, `mockk(`, `every {` | unit-test |

## Các phần đầu ra bắt buộc (Mandatory output sections)

Đưa vào nếu phát hiện thấy (liệt kê tên thực tế tìm được):
- **Danh mục tính năng (Features inventory)**: các thư mục dưới `feature/`
- **Các mô-đun cốt lõi (Core modules)**: các thư mục dưới `core/`, `library/`
- **Đồ thị điều hướng (Navigation graphs)**: `*Graph.kt`, `*Navigator*.kt`
- **Các mô-đun Hilt (Hilt modules)**: các lớp `@Module`, nội dung trong `di/`
- **Các API Retrofit (Retrofit APIs)**: các interface `*Api.kt`
- **Cơ sở dữ liệu Room (Room databases)**: các lớp `@Database`
- **Các tiến trình nền (Workers)**: các lớp `@HiltWorker`
- **Proguard**: `proguard-rules.pro` nếu có

## Nguồn trích xuất lệnh (Command sources)
- Tài liệu README/docs có gọi lệnh `./gradlew`
- Các luồng công việc CI (CI workflows) có chứa các lệnh Gradle
- Các lệnh phổ biến: `./gradlew assemble`, `./gradlew test`, `./gradlew lint`
- Chỉ đưa vào những lệnh thực sự tồn tại trong repo

## Các đường dẫn chính (Key paths)
- `app/src/main/`, `app/src/main/res/`
- `app/src/main/java/`, `app/src/main/kotlin/`
- `app/src/test/`, `app/src/androidTest/`
- `library/database/migration/` (các bản di trú dữ liệu Room - Room migrations)
FILE:README.md

FILE:references/cpp.md
# C/C++

## Tín hiệu nhận diện
- `CMakeLists.txt`
- `Makefile`, `makefile`
- `*.cpp`, `*.c`, `*.h`, `*.hpp`
- `conanfile.txt`, `conanfile.py` (Conan)
- `vcpkg.json` (vcpkg)

## Tín hiệu đa mô-đun (Multi-module signals)
- Nhiều tệp `CMakeLists.txt` có sử dụng `add_subdirectory`
- Nhiều tệp `Makefile` trong các thư mục con
- Các thư mục `lib/`, `src/`, `modules/`

## Các nguồn kiểm tra trước khi tạo (Pre-generation sources)
- `CMakeLists.txt` (các thư viện phụ thuộc, mục tiêu biên dịch - targets)
- `conanfile.*` (các thư viện phụ thuộc)
- `vcpkg.json` (các thư viện phụ thuộc)
- `Makefile` (các mục tiêu biên dịch - build targets)

## Các mẫu quét mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `src/`, `lib/`, `include/`

### Các mẫu phân tầng/thư mục (ghi nhận nếu có)
`core/`, `utils/`, `network/`, `storage/`, `ui/`, `tests/`

### Các dấu hiệu nhận biết mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Nhận diện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| Class | `class *`, `public:`, `private:` | cpp-class |
| Header | `*.h`, `*.hpp`, `#pragma once` | header-file |
| Template | `template<`, `typename T` | cpp-template |
| Smart Pointer | `std::unique_ptr`, `std::shared_ptr` | smart-pointer |
| RAII | mẫu hàm hủy (destructor pattern), `~*()` | raii-pattern |
| Singleton | `static *& instance()` | singleton |
| Factory | `create*()`, `make*()` | factory-pattern |
| Observer | `subscribe`, `notify`, mẫu hàm gọi lại (callback pattern) | observer-pattern |
| Thread | `std::thread`, `std::async`, `pthread` | threading |
| Mutex | `std::mutex`, `std::lock_guard` | synchronization |
| Network | `socket`, `asio::`, `boost::asio` | network-cpp |
| Serialization | `nlohmann::json`, `protobuf` | serialization |
| Unit Test | `TEST(`, `TEST_F(`, `gtest` | gtest |
| Catch2 Test | `TEST_CASE(`, `REQUIRE(` | catch2-test |

## Các phần đầu ra bắt buộc (Mandatory output sections)

Đưa vào nếu phát hiện thấy:
- **Các mô-đun cốt lõi (Core modules)**: chức năng chính
- **Thư viện (Libraries)**: các thư viện nội bộ
- **Tệp tiêu đề (Headers)**: API công khai
- **Kiểm thử (Tests)**: cách tổ chức kiểm thử
- **Mục tiêu biên dịch (Build targets)**: các tệp thực thi (executables), thư viện

## Nguồn trích xuất lệnh (Command sources)
- Các mục tiêu tùy chỉnh (custom targets) trong `CMakeLists.txt`
- Các mục tiêu trong `Makefile`
- README/docs, CI
- Các lệnh phổ biến: `cmake`, `make`, `ctest`
- Chỉ đưa vào những lệnh thực sự tồn tại trong repo

## Các đường dẫn chính (Key paths)
- `src/`, `include/`
- `lib/`, `libs/`
- `tests/`, `test/`
- `build/` (biên dịch tách rời mã nguồn - out-of-source)
FILE:references/dotnet.md
# .NET (C#/F#)

## Tín hiệu nhận diện
- `*.csproj`, `*.fsproj`
- `*.sln`
- `global.json`
- `appsettings.json`
- `Program.cs`, `Startup.cs`

## Tín hiệu đa mô-đun (Multi-module signals)
- Nhiều tệp `*.csproj`
- Solution chứa nhiều dự án (projects)
- Các thư mục `src/`, `tests/` có chứa các dự án bên trong

## Các nguồn kiểm tra trước khi tạo (Pre-generation sources)
- `*.csproj` (các gói phụ thuộc, SDK)
- `*.sln` (cấu trúc dự án)
- `appsettings.json` (cấu hình)
- `global.json` (phiên bản SDK)

## Các mẫu quét mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `src/`, `*/` (theo từng dự án)

### Các mẫu phân tầng/thư mục (ghi nhận nếu có)
`Controllers/`, `Services/`, `Repositories/`, `Models/`, `Entities/`, `DTOs/`, `Middleware/`, `Extensions/`

### Các dấu hiệu nhận biết mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Nhận diện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| Controller | `[ApiController]`, `ControllerBase`, `[HttpGet]` | aspnet-controller |
| Service | `I*Service`, `class *Service` | dotnet-service |
| Repository | `I*Repository`, `class *Repository` | dotnet-repository |
| Entity | `class *Entity`, `[Table]`, `[Key]` | ef-entity |
| DTO | `class *Dto`, `class *Request`, `class *Response` | dto-pattern |
| DbContext | `: DbContext`, `DbSet<` | ef-dbcontext |
| Middleware | `IMiddleware`, `RequestDelegate` | aspnet-middleware |
| Background Service | `BackgroundService`, `IHostedService` | background-service |
| MediatR Handler | `IRequestHandler<`, `INotificationHandler<` | mediatr-handler |
| SignalR Hub | `: Hub`, `[HubName]` | signalr-hub |
| Minimal API | `app.MapGet(`, `app.MapPost(` | minimal-api |
| gRPC Service | `*.proto`, `: *Base` | grpc-service |
| EF Migration | `Migrations/`, `AddMigration` | ef-migration |
| Unit Test | `[Fact]`, `[Theory]`, `xUnit` | xunit-test |
| Integration Test | `WebApplicationFactory`, `IClassFixture` | integration-test |

## Các phần đầu ra bắt buộc (Mandatory output sections)

Đưa vào nếu phát hiện thấy:
- **Controllers**: các điểm cuối API (API endpoints)
- **Services**: logic nghiệp vụ
- **Repositories**: truy cập dữ liệu (EF Core)
- **Entities/DTOs**: các mô hình dữ liệu (data models)
- **Middleware**: đường ống xử lý yêu cầu (request pipeline)
- **Background services**: các dịch vụ chạy nền (hosted services)

## Nguồn trích xuất lệnh (Command sources)
- Các mục tiêu trong `*.csproj`
- README/docs, CI
- Các lệnh phổ biến: `dotnet build`, `dotnet test`, `dotnet run`
- Chỉ đưa vào những lệnh thực sự tồn tại trong repo

## Các đường dẫn chính (Key paths)
- `src/*/`, các thư mục dự án
- `tests/`
- `Migrations/`
- `Properties/`
FILE:references/elixir.md
# Elixir/Erlang

## Tín hiệu nhận diện
- `mix.exs`
- `mix.lock`
- `config/config.exs`
- Các thư mục `lib/`, `test/`

## Tín hiệu đa mô-đun (Multi-module signals)
- Ứng dụng dạng Umbrella (thư mục `apps/`)
- Nhiều tệp `mix.exs` trong các thư mục con
- Thư mục `rel/` dành cho các bản phát hành (releases)

## Các nguồn kiểm tra trước khi tạo (Pre-generation sources)
- `mix.exs` (các thư viện phụ thuộc, cấu hình)
- `config/*.exs` (cấu hình)
- `rel/config.exs` (bản phát hành)

## Các mẫu quét mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `lib/`, `apps/*/lib/`

### Các mẫu phân tầng/thư mục (ghi nhận nếu có)
`controllers/`, `views/`, `channels/`, `contexts/`, `schemas/`, `workers/`

### Các dấu hiệu nhận biết mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Nhận diện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| Phoenix Controller | `use *Web, :controller`, `def index` | phoenix-controller |
| Phoenix LiveView | `use *Web, :live_view`, `mount/3` | phoenix-liveview |
| Phoenix Channel | `use *Web, :channel`, `join/3` | phoenix-channel |
| Ecto Schema | `use Ecto.Schema`, `schema "` | ecto-schema |
| Ecto Migration | `use Ecto.Migration`, `create table` | ecto-migration |
| Ecto Changeset | `cast/4`, `validate_required` | ecto-changeset |
| Context | `defmodule *Context`, `def list_*` | phoenix-context |
| GenServer | `use GenServer`, `handle_call` | genserver |
| Supervisor | `use Supervisor`, `start_link` | supervisor |
| Task | `Task.async`, `Task.Supervisor` | elixir-task |
| Oban Worker | `use Oban.Worker`, `perform/1` | oban-worker |
| Absinthe | `use Absinthe.Schema`, `field :` | graphql-schema |
| ExUnit Test | `use ExUnit.Case`, `test "` | exunit-test |

## Các phần đầu ra bắt buộc (Mandatory output sections)

Đưa vào nếu phát hiện thấy:
- **Controllers/LiveViews**: các trình xử lý HTTP/WebSocket
- **Contexts**: logic nghiệp vụ
- **Schemas**: các mô hình dữ liệu Ecto (Ecto models)
- **Channels**: các trình xử lý thời gian thực (real-time handlers)
- **Workers**: các tác vụ chạy nền (background jobs)

## Nguồn trích xuất lệnh (Command sources)
- Các bí danh (aliases) trong `mix.exs`
- README/docs, CI
- Các lệnh phổ biến: `mix deps.get`, `mix test`, `mix phx.server`
- Chỉ đưa vào những lệnh thực sự tồn tại trong repo

## Các đường dẫn chính (Key paths)
- `lib/*/`, `lib/*_web/`
- `priv/repo/migrations/`
- `test/`
- `config/`
FILE:references/flutter.md
# Flutter/Dart

## Tín hiệu nhận diện
- `pubspec.yaml`
- `lib/main.dart`
- Các thư mục `android/`, `ios/`, `web/`
- `.dart_tool/`
- `analysis_options.yaml`

## Tín hiệu đa mô-đun (Multi-module signals)
- `melos.yaml` (monorepo)
- Nhiều tệp `pubspec.yaml` trong các thư mục con
- Thư mục `packages/`

## Các nguồn kiểm tra trước khi tạo (Pre-generation sources)
- `pubspec.yaml` (các thư viện phụ thuộc)
- `analysis_options.yaml`
- `build.yaml` (nếu sử dụng build_runner)
- `lib/main.dart` (điểm khởi chạy ứng dụng - entry point)

## Các mẫu quét mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `lib/`, `test/`

### Các mẫu phân tầng/thư mục (ghi nhận nếu có)
`screens/`, `widgets/`, `models/`, `services/`, `providers/`, `repositories/`, `utils/`, `constants/`, `bloc/`, `cubit/`

### Các dấu hiệu nhận biết mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Nhận diện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| Screen/Page | `*Screen`, `*Page`, `extends StatefulWidget` | flutter-screen |
| Widget | `extends StatelessWidget`, `extends StatefulWidget` | flutter-widget |
| BLoC | `extends Bloc<`, `extends Cubit<` | bloc-pattern |
| Provider | `ChangeNotifier`, `Provider.of<`, `context.read<` | provider-pattern |
| Riverpod | `@riverpod`, `ref.watch`, `ConsumerWidget` | riverpod-provider |
| GetX | `GetxController`, `Get.put`, `Obx(` | getx-controller |
| Repository | `*Repository`, `abstract class *Repository` | data-repository |
| Service | `*Service` | service-layer |
| Model | `fromJson`, `toJson`, `@JsonSerializable` | json-model |
| Freezed | `@freezed`, `part '*.freezed.dart'` | freezed-model |
| API Client | `Dio`, `http.Client`, `Retrofit` | api-client |
| Navigation | `Navigator`, `GoRouter`, `auto_route` | flutter-navigation |
| Localization | `AppLocalizations`, `l10n`, `intl` | flutter-l10n |
| Testing | `testWidgets`, `WidgetTester`, `flutter_test` | widget-test |
| Integration Test | `integration_test`, `IntegrationTestWidgetsFlutterBinding` | integration-test |

## Các phần đầu ra bắt buộc (Mandatory output sections)

Đưa vào nếu phát hiện thấy:
- **Danh mục màn hình (Screens inventory)**: các thư mục dưới `screens/`, `pages/`
- **Quản lý trạng thái (State management)**: BLoC, Provider, Riverpod, GetX
- **Thiết lập điều hướng (Navigation setup)**: GoRouter, auto_route, Navigator
- **Phương pháp tiêm phụ thuộc (DI approach)**: get_it, injectable, thủ công (manual)
- **Tầng API (API layer)**: Dio, http, Retrofit
- **Các mô hình dữ liệu (Models)**: Freezed, json_serializable

## Nguồn trích xuất lệnh (Command sources)
- Các kịch bản (scripts) trong `pubspec.yaml` (nếu sử dụng melos)
- README/docs
- Các lệnh phổ biến: `flutter run`, `flutter test`, `flutter build`
- Chỉ đưa vào những lệnh thực sự tồn tại trong repo

## Các đường dẫn chính (Key paths)
- `lib/`, `test/`
- `lib/screens/`, `lib/widgets/`
- `lib/bloc/`, `lib/providers/`
- `assets/`
FILE:references/generic.md
# Ngăn xếp Công nghệ Chung / Không xác định (Generic/Unknown Stack)

Tài liệu tham khảo dự phòng khi không phát hiện được nền tảng cụ thể nào.

## Tín hiệu nhận diện
- Không tìm thấy tệp biên dịch/cấu hình đặc thù nào
- Ngăn xếp công nghệ pha trộn (Mixed technology stack)
- Kho lưu trữ (repository) chỉ chứa tài liệu

## Tín hiệu đa mô-đun (Multi-module signals)
- Nhiều thư mục tách biệt theo từng mối quan tâm (separate concerns)
- Các thư mục `packages/`, `modules/`, `libs/`
- Cấu trúc monorepo không sử dụng bộ công cụ đặc thù

## Các nguồn kiểm tra trước khi tạo (Pre-generation sources)
- `README.md` (tổng quan dự án)
- `docs/*` (tài liệu)
- `.env.example` (các biến môi trường)
- `docker-compose.yml` (các dịch vụ - services)
- Các tệp CI (`.github/workflows/`, v.v.)

## Các mẫu quét mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `src/`, `lib/`, `app/`

### Các mẫu phân tầng/thư mục (ghi nhận nếu có)
`api/`, `core/`, `utils/`, `services/`, `models/`, `config/`, `scripts/`

### Các dấu hiệu nhận biết mẫu chung (Generic pattern indicators)

| Mẫu (Pattern) | Tiêu chí Nhận diện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| Entry Point | `main.*`, `index.*`, `app.*` | entry-point |
| Config | `config.*`, `settings.*` | config-file |
| API Client | `api/`, `client/`, các lệnh gọi HTTP | api-client |
| Model | `model/`, `types/`, các cấu trúc dữ liệu | data-model |
| Service | `service/`, logic nghiệp vụ | service-layer |
| Utility | `utils/`, `helpers/`, `common/` | utility-module |
| Test | `test/`, `tests/`, `*_test.*`, `*.test.*` | test-file |
| Script | `scripts/`, `bin/` | script-file |
| Documentation | `docs/`, `*.md` | documentation |

## Các phần đầu ra bắt buộc (Mandatory output sections)

Đưa vào nếu phát hiện thấy:
- **Cấu trúc dự án (Project structure)**: các thư mục chính
- **Điểm khởi chạy (Entry points)**: các tệp chính
- **Cấu hình (Configuration)**: các tệp cấu hình
- **Thư viện phụ thuộc (Dependencies)**: bất kỳ trình quản lý gói nào
- **Các lệnh Build/Run**: trích xuất từ README/scripts

## Nguồn trích xuất lệnh (Command sources)
- `README.md` (tìm các khối mã - code blocks)
- `Makefile`, `Taskfile.yml`
- Thư mục `scripts/`
- Các luồng công việc CI (CI workflows)
- Chỉ đưa vào những lệnh thực sự tồn tại trong repo

## Các đường dẫn chính (Key paths)
- `src/`, `lib/`
- `docs/`
- `scripts/`
- `config/`

## Ghi chú

Khi sử dụng tài liệu tham khảo chung này:
1. Quét tìm bất kỳ mẫu kiến trúc nào có thể nhận diện được
2. Ghi chép lại cấu trúc dự án thực tế tìm thấy
3. Trích xuất các lệnh từ README nếu có sẵn
4. Ghi chú lại bất kỳ công nghệ nào được nhắc đến trong tài liệu (docs)
5. Giữ cho đầu ra tối giản và bám sát thực tế
FILE:references/go.md
# Go

## Tín hiệu nhận diện
- `go.mod`
- `go.sum`
- `main.go`
- Các thư mục `cmd/`, `internal/`, `pkg/`

## Tín hiệu đa mô-đun (Multi-module signals)
- `go.work` (workspace)
- Nhiều tệp `go.mod`
- `cmd/*/main.go` (nhiều tệp thực thi binary)

## Các nguồn kiểm tra trước khi tạo (Pre-generation sources)
- `go.mod` (các gói phụ thuộc)
- `Makefile` (các lệnh biên dịch)
- `config/*.yaml` hoặc `*.toml`

## Các mẫu quét mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `cmd/`, `internal/`, `pkg/`

### Các mẫu phân tầng/thư mục (ghi nhận nếu có)
`handler/`, `service/`, `repository/`, `model/`, `middleware/`, `config/`, `util/`

### Các dấu hiệu nhận biết mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Nhận diện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| HTTP Handler | `http.Handler`, `http.HandlerFunc`, `gin.Context` | http-handler |
| Gin Route | `gin.Engine`, `r.GET(`, `r.POST(` | gin-route |
| Echo Route | `echo.Echo`, `e.GET(`, `e.POST(` | echo-route |
| Fiber Route | `fiber.App`, `app.Get(`, `app.Post(` | fiber-route |
| gRPC Service | `*.proto`, `pb.*Server` | grpc-service |
| Repository | `type *Repository interface`, `*Repository` | data-repository |
| Service | `type *Service interface`, `*Service` | service-layer |
| GORM Model | `gorm.Model`, `*gorm.DB` | gorm-model |
| sqlx | `sqlx.DB`, `sqlx.NamedExec` | sqlx-usage |
| Migration | `goose`, `golang-migrate` | db-migration |
| Middleware | `func(*Context)`, `middleware.*` | go-middleware |
| Worker | `go func()`, `sync.WaitGroup`, `errgroup` | worker-goroutine |
| Config | `viper`, `envconfig`, `cleanenv` | config-loader |
| Unit Test | `*_test.go`, `func Test*(t *testing.T)` | go-test |
| Mock | `mockgen`, `*_mock.go` | go-mock |

## Các phần đầu ra bắt buộc (Mandatory output sections)

Đưa vào nếu phát hiện thấy:
- **HTTP handlers**: các điểm cuối API (API endpoints)
- **Services**: logic nghiệp vụ
- **Repositories**: truy cập dữ liệu
- **Models**: các cấu trúc dữ liệu (data structures)
- **Middleware**: các bộ chặn xử lý yêu cầu (request interceptors)
- **Migrations**: các bản di trú cơ sở dữ liệu (database migrations)

## Nguồn trích xuất lệnh (Command sources)
- Các mục tiêu trong `Makefile`
- README/docs, CI
- Các lệnh phổ biến: `go build`, `go test`, `go run`
- Chỉ đưa vào những lệnh thực sự tồn tại trong repo

## Các đường dẫn chính (Key paths)
- `cmd/`, `internal/`, `pkg/`
- `api/`, `handler/`
- `migrations/`
- `config/`
FILE:references/ios.md
# iOS (Xcode/Swift)

## Tín hiệu nhận diện
- `*.xcodeproj`, `*.xcworkspace`
- `Package.swift` (SPM)
- `Podfile`, `Podfile.lock` (CocoaPods)
- `Cartfile` (Carthage)
- `*.pbxproj`
- `Info.plist`

## Tín hiệu đa mô-đun (Multi-module signals)
- Nhiều mục tiêu (targets) trong `*.xcodeproj`
- Nhiều tệp `Package.swift`
- Workspace chứa nhiều dự án (projects)
- Các thư mục `Modules/`, `Packages/`, `Features/`

## Các nguồn kiểm tra trước khi tạo (Pre-generation sources)
- `*.xcodeproj/project.pbxproj` (danh sách target)
- `Package.swift` (các gói phụ thuộc, targets)
- `Podfile` (các gói phụ thuộc)
- `*.xcconfig` (cấu hình biên dịch - build configs)
- Các tệp `Info.plist`

## Các mẫu quét mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `*/Sources/`, `*/Source/`
- `*/App/`, `*/Core/`, `*/Features/`

### Các mẫu phân tầng/thư mục (ghi nhận nếu có)
`Models/`, `Views/`, `ViewModels/`, `Services/`, `Networking/`, `Utilities/`, `Extensions/`, `Coordinators/`

### Các dấu hiệu nhận biết mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Nhận diện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| SwiftUI View | `struct *: View`, `var body: some View` | swiftui-view |
| UIKit VC | `UIViewController`, `viewDidLoad()` | uikit-viewcontroller |
| ViewModel | `@Observable`, `ObservableObject`, `@Published` | viewmodel-observable |
| Coordinator | `Coordinator`, `*Coordinator` | coordinator-pattern |
| Repository | `*Repository`, `protocol *Repository` | data-repository |
| Service | `*Service`, `protocol *Service` | service-layer |
| Core Data | `NSManagedObject`, `@NSManaged`, `.xcdatamodeld` | coredata-entity |
| Realm | `Object`, `@Persisted` | realm-model |
| Network | `URLSession`, `Alamofire`, `Moya` | network-client |
| Dependency | `@Inject`, `Container`, `Swinject` | di-container |
| Navigation | `NavigationStack`, `NavigationPath` | navigation-swiftui |
| Combine | `Publisher`, `AnyPublisher`, `sink` | combine-publisher |
| Async/Await | `async`, `await`, `Task {` | async-await |
| Unit Test | `XCTestCase`, `func test*()` | xctest |
| UI Test | `XCUIApplication`, `XCUIElement` | xcuitest |

## Các phần đầu ra bắt buộc (Mandatory output sections)

Đưa vào nếu phát hiện thấy:
- **Danh mục targets (Targets inventory)**: danh sách trích xuất từ pbxproj
- **Modules/Packages**: các gói SPM, Pods
- **Kiến trúc View (View architecture)**: SwiftUI so với UIKit
- **Quản lý trạng thái (State management)**: Combine, Observable, v.v.
- **Tầng mạng (Networking layer)**: URLSession, Alamofire, v.v.
- **Lưu trữ bền vững (Persistence)**: Core Data, Realm, UserDefaults
- **Thiết lập DI (DI setup)**: Swinject, tiêm phụ thuộc thủ công (manual injection)

## Nguồn trích xuất lệnh (Command sources)
- Tài liệu README/docs có chứa các lệnh xcodebuild
- Các lane trong `fastlane/Fastfile`
- Các luồng công việc CI (`.github/workflows/`, `.gitlab-ci.yml`)
- Các lệnh phổ biến: `xcodebuild test`, `fastlane test`
- Chỉ đưa vào những lệnh thực sự tồn tại trong repo

## Các đường dẫn chính (Key paths)
- `*/Sources/`, `*/Tests/`
- `*.xcodeproj/`, `*.xcworkspace/`
- `Pods/` (nếu sử dụng CocoaPods)
- `Packages/` (nếu sử dụng các gói SPM cục bộ)
FILE:references/java.md
# Java/JVM (Spring, v.v.)

## Tín hiệu nhận diện
- `pom.xml` (Maven)
- `build.gradle`, `build.gradle.kts` (Gradle)
- `settings.gradle` (đa mô-đun - multi-module)
- `src/main/java/`, `src/main/kotlin/`
- `application.properties`, `application.yml`

## Tín hiệu đa mô-đun (Multi-module signals)
- Nhiều tệp `pom.xml` có thẻ `<modules>`
- Nhiều tệp `build.gradle` có lệnh `include()`
- Các thư mục `modules/`, `services/`

## Các nguồn kiểm tra trước khi tạo (Pre-generation sources)
- `pom.xml` hoặc `build.gradle*` (các thư viện phụ thuộc)
- `application.properties/yml` (cấu hình)
- `settings.gradle` (danh sách mô-đun)
- `docker-compose.yml` (các dịch vụ - services)

## Các mẫu quét mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `src/main/java/`, `src/main/kotlin/`
- `src/test/java/`, `src/test/kotlin/`

### Các mẫu phân tầng/thư mục (ghi nhận nếu có)
`controller/`, `service/`, `repository/`, `model/`, `entity/`, `dto/`, `config/`, `exception/`, `util/`

### Các dấu hiệu nhận biết mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Nhận diện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| REST Controller | `@RestController`, `@GetMapping`, `@PostMapping` | spring-controller |
| Service | `@Service`, `class *Service` | spring-service |
| Repository | `@Repository`, `JpaRepository`, `CrudRepository` | spring-repository |
| Entity | `@Entity`, `@Table`, `@Id` | jpa-entity |
| DTO | `class *DTO`, `class *Request`, `class *Response` | dto-pattern |
| Config | `@Configuration`, `@Bean` | spring-config |
| Component | `@Component`, `@Autowired` | spring-component |
| Security | `@EnableWebSecurity`, `SecurityFilterChain` | spring-security |
| Validation | `@Valid`, `@NotNull`, `@Size` | validation-pattern |
| Exception Handler | `@ControllerAdvice`, `@ExceptionHandler` | exception-handler |
| Scheduler | `@Scheduled`, `@EnableScheduling` | scheduled-task |
| Event | `ApplicationEvent`, `@EventListener` | event-listener |
| Flyway Migration | `V*__*.sql`, `flyway` | flyway-migration |
| Liquibase | `changelog*.xml`, `liquibase` | liquibase-migration |
| Unit Test | `@Test`, `@SpringBootTest`, `MockMvc` | spring-test |
| Integration Test | `@DataJpaTest`, `@WebMvcTest` | integration-test |

## Các phần đầu ra bắt buộc (Mandatory output sections)

Đưa vào nếu phát hiện thấy:
- **Controllers**: các điểm cuối REST (REST endpoints)
- **Services**: logic nghiệp vụ
- **Repositories**: truy cập dữ liệu (JPA, JDBC)
- **Entities/DTOs**: các mô hình dữ liệu (data models)
- **Configuration**: các Spring beans, cấu hình theo môi trường (profiles)
- **Security**: cấu hình xác thực/phân quyền (auth config)

## Nguồn trích xuất lệnh (Command sources)
- Các plugin trong `pom.xml`, các tác vụ (tasks) trong `build.gradle`
- README/docs, CI
- Các lệnh phổ biến: `./mvnw`, `./gradlew`, `mvn test`, `gradle test`
- Chỉ đưa vào những lệnh thực sự tồn tại trong repo

## Các đường dẫn chính (Key paths)
- `src/main/java/`, `src/main/kotlin/`
- `src/main/resources/`
- `src/test/`
- `db/migration/` (Flyway)
FILE:references/node.md
# Node.js

## Tín hiệu nhận diện
- `package.json` (không chứa react/react-native)
- `tsconfig.json`
- `node_modules/`
- Các tệp khởi chạy `*.js`, `*.ts`, `*.mjs`, `*.cjs`

## Tín hiệu đa mô-đun (Multi-module signals)
- `pnpm-workspace.yaml`, `lerna.json`
- `nx.json`, `turbo.json`
- Nhiều tệp `package.json` trong các thư mục con
- Các thư mục `packages/`, `apps/`

## Các nguồn kiểm tra trước khi tạo (Pre-generation sources)
- `package.json` (các gói phụ thuộc, kịch bản scripts)
- `tsconfig.json` (đường dẫn paths, tùy chọn trình biên dịch)
- `.env.example` (các biến môi trường)
- `docker-compose.yml` (các dịch vụ - services)

## Các mẫu quét mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `src/`, `lib/`, `app/`

### Các mẫu phân tầng/thư mục (ghi nhận nếu có)
`controllers/`, `services/`, `models/`, `routes/`, `middleware/`, `utils/`, `config/`, `types/`, `repositories/`

### Các dấu hiệu nhận biết mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Nhận diện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| Express Route | `app.get(`, `app.post(`, `Router()` | express-route |
| Express Middleware | `(req, res, next)`, `app.use(` | express-middleware |
| NestJS Controller | `@Controller`, `@Get`, `@Post` | nestjs-controller |
| NestJS Service | `@Injectable`, `@Service` | nestjs-service |
| NestJS Module | `@Module`, `imports:`, `providers:` | nestjs-module |
| Fastify Route | `fastify.get(`, `fastify.post(` | fastify-route |
| GraphQL Resolver | `@Resolver`, `@Query`, `@Mutation` | graphql-resolver |
| TypeORM Entity | `@Entity`, `@Column`, `@PrimaryGeneratedColumn` | typeorm-entity |
| Prisma Model | `prisma.*.create`, `prisma.*.findMany` | prisma-usage |
| Mongoose Model | `mongoose.Schema`, `mongoose.model(` | mongoose-model |
| Sequelize Model | `Model.init`, `DataTypes` | sequelize-model |
| Queue Worker | `Bull`, `BullMQ`, `process(` | queue-worker |
| Tác vụ định kỳ (Cron Job) | `@Cron`, `node-cron`, `cron.schedule` | cron-job |
| WebSocket | `ws`, `socket.io`, `io.on(` | websocket-handler |
| Kiểm thử đơn vị (Unit Test) | `describe(`, `it(`, `expect(`, `jest` | jest-test |
| Kiểm thử đầu cuối (E2E Test) | `supertest`, `request(app)` | e2e-test |

## Các phần đầu ra bắt buộc

Đưa vào nếu phát hiện thấy:
- **Routes/controllers**: các điểm cuối (endpoints) API
- **Tầng Services**: logic nghiệp vụ
- **Cơ sở dữ liệu (Database)**: cách sử dụng ORM/ODM (TypeORM, Prisma, Mongoose)
- **Middleware**: xác thực (auth), kiểm tra dữ liệu (validation), xử lý lỗi
- **Tác vụ chạy ngầm (Background jobs)**: hàng đợi (queues), tác vụ định kỳ (cron jobs)
- **Trình xử lý WebSocket (WebSocket handlers)**: các tính năng thời gian thực

## Nguồn câu lệnh
- Mục scripts trong `package.json`
- Tệp README/tài liệu (docs)
- Các luồng công việc CI (CI workflows)
- Phổ biến: `npm run dev`, `npm run build`, `npm test`
- Chỉ đưa vào những câu lệnh thực sự tồn tại trong kho mã nguồn (repo)

## Các đường dẫn chính
- `src/`, `lib/`
- `src/routes/`, `src/controllers/`
- `src/services/`, `src/models/`
- `prisma/`, `migrations/`
FILE:references/php.md
# PHP

## Dấu hiệu nhận diện
- `composer.json`, `composer.lock`
- `public/index.php`
- `artisan` (Laravel)
- `spark` (CodeIgniter 4)
- `bin/console` (Symfony)
- `app/Config/App.php` (CodeIgniter 4)
- `ext-phalcon` trong composer.json (Phalcon)
- `phalcon/devtools` (Phalcon)

## Dấu hiệu đa mô-đun (Multi-module)
- Thư mục `packages/`
- Các mô-đun Laravel (`app/Modules/`)
- Các mô-đun CodeIgniter (`app/Modules/`, `modules/`)
- Phalcon đa ứng dụng (`apps/*/`)
- Nhiều tệp `composer.json` trong các thư mục con

## Nguồn phân tích trước khi tạo
- `composer.json` (các gói phụ thuộc)
- `.env.example` (các biến môi trường)
- `config/*.php` (Laravel/Symfony)
- `routes/*.php` (Laravel)
- `app/Config/*` (CodeIgniter 4)
- `apps/*/config/` (Phalcon)

## Các mẫu quét kho mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `app/`, `src/`, `apps/`

### Các mẫu tầng/thư mục (ghi nhận nếu có mặt)
`Controllers/`, `Services/`, `Repositories/`, `Models/`, `Entities/`, `Http/`, `Providers/`, `Console/`

### Cấu trúc đặc thù theo từng Framework

**Laravel** (ghi nhận nếu có mặt):
- `app/Http/Controllers`, `app/Models`, `database/migrations`
- `routes/*.php`, `resources/views`

**Symfony** (ghi nhận nếu có mặt):
- `src/Controller`, `src/Entity`, `config/packages`, `templates`

**CodeIgniter 4** (ghi nhận nếu có mặt):
- `app/Controllers`, `app/Models`, `app/Views`
- `app/Config/Routes.php`, `app/Database/Migrations`

**Phalcon** (ghi nhận nếu có mặt):
- `apps/*/controllers/`, `apps/*/Module.php`
- `models/`, `views/`

### Các chỉ báo mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Phát hiện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| Laravel Controller | `extends Controller`, `public function index` | laravel-controller |
| Laravel Model | `extends Model`, `protected $fillable` | laravel-model |
| Laravel Migration | `extends Migration`, `Schema::create` | laravel-migration |
| Laravel Service | `class *Service`, `app/Services/` | laravel-service |
| Laravel Repository | `*Repository`, `interface *Repository` | laravel-repository |
| Laravel Job | `implements ShouldQueue`, `dispatch(` | laravel-job |
| Laravel Event | `extends Event`, `event(` | laravel-event |
| Symfony Controller | `#[Route]`, `AbstractController` | symfony-controller |
| Symfony Service | `#[AsService]`, `services.yaml` | symfony-service |
| Doctrine Entity | `#[ORM\Entity]`, `#[ORM\Column]` | doctrine-entity |
| Doctrine Migration | `AbstractMigration`, `$this->addSql` | doctrine-migration |
| CI4 Controller | `extends BaseController`, `app/Controllers/` | ci4-controller |
| CI4 Model | `extends Model`, `protected $table` | ci4-model |
| CI4 Migration | `extends Migration`, `$this->forge->` | ci4-migration |
| CI4 Entity | `extends Entity`, `app/Entities/` | ci4-entity |
| Phalcon Controller | `extends Controller`, `Phalcon\Mvc\Controller` | phalcon-controller |
| Phalcon Model | `extends Model`, `Phalcon\Mvc\Model` | phalcon-model |
| Phalcon Migration | `Phalcon\Migrations`, `morphTable` | phalcon-migration |
| API Resource | `extends JsonResource`, `toArray` | api-resource |
| Form Request | `extends FormRequest`, `rules()` | form-request |
| Middleware | `implements Middleware`, `handle(` | php-middleware |
| Unit Test | `extends TestCase`, `test*()`, `PHPUnit` | phpunit-test |
| Feature Test | `extends TestCase`, `$this->get(`, `$this->post(` | feature-test |

## Các phần đầu ra bắt buộc

Đưa vào nếu phát hiện thấy:
- **Controllers**: các điểm cuối (endpoints) HTTP
- **Models/Entities**: tầng dữ liệu
- **Services**: logic nghiệp vụ
- **Repositories**: truy cập dữ liệu
- **Migrations**: các thay đổi cơ sở dữ liệu
- **Jobs/Events**: xử lý bất đồng bộ
- **Các mô-đun nghiệp vụ (Business modules)**: các mô-đun lớn nhất theo quy mô

## Nguồn câu lệnh
- Mục scripts trong `composer.json`
- `php artisan` (Laravel)
- `php spark` (CodeIgniter 4)
- `bin/console` (Symfony)
- Các lệnh công cụ phát triển `phalcon`
- README/docs, CI
- Chỉ đưa vào những câu lệnh thực sự tồn tại trong kho mã nguồn

## Các đường dẫn chính

**Laravel:**
- `app/`, `routes/`, `database/migrations/`
- `resources/views/`, `tests/`

**Symfony:**
- `src/`, `config/`, `templates/`
- `migrations/`, `tests/`

**CodeIgniter 4:**
- `app/Controllers/`, `app/Models/`, `app/Views/`
- `app/Database/Migrations/`, `tests/`

**Phalcon:**
- `apps/*/controllers/`, `apps/*/models/`
- `apps/*/views/`, `migrations/`
FILE:references/python.md
# Python

## Dấu hiệu nhận diện
- `pyproject.toml`
- `requirements.txt`, `requirements-dev.txt`
- `Pipfile`, `poetry.lock`
- `setup.py`, `setup.cfg`
- `manage.py` (Django)

## Dấu hiệu đa mô-đun (Multi-module)
- Nhiều tệp `pyproject.toml` trong các thư mục con
- Các thư mục `packages/`, `apps/`
- Thư mục `apps/` kiểu Django có chứa `apps.py`

## Nguồn phân tích trước khi tạo
- `pyproject.toml` hoặc `setup.py`
- `requirements*.txt`, `Pipfile`
- `tox.ini`, `pytest.ini`
- `manage.py`, `settings.py` (Django)

## Các mẫu quét kho mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `src/`, `app/`, `packages/`, `tests/`

### Các mẫu tầng/thư mục (ghi nhận nếu có mặt)
`api/`, `routers/`, `views/`, `services/`, `repositories/`, `models/`, `schemas/`, `utils/`, `config/`

### Các chỉ báo mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Phát hiện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| FastAPI Router | `APIRouter`, `@router.get`, `@router.post` | fastapi-router |
| FastAPI Dependency | `Depends(`, `def get_*():` | fastapi-dependency |
| Django View | `View`, `APIView`, `def get(self, request)` | django-view |
| Django Model | `models.Model`, `class Meta:` | django-model |
| Django Serializer | `serializers.Serializer`, `ModelSerializer` | drf-serializer |
| Flask Route | `@app.route`, `Blueprint` | flask-route |
| Pydantic Model | `BaseModel`, `Field(`, `model_validator` | pydantic-model |
| SQLAlchemy Model | `Base`, `Column(`, `relationship(` | sqlalchemy-model |
| Alembic Migration | `alembic/versions/`, `op.create_table` | alembic-migration |
| Repository | `*Repository`, `class *Repository` | data-repository |
| Service | `*Service`, `class *Service` | service-layer |
| Celery Task | `@celery.task`, `@shared_task` | celery-task |
| CLI Command | `@click.command`, `typer.Typer` | cli-command |
| Unit Test | `pytest`, `def test_*():`, `unittest` | pytest-test |
| Fixture | `@pytest.fixture`, `conftest.py` | pytest-fixture |

## Các phần đầu ra bắt buộc

Đưa vào nếu phát hiện thấy:
- **Routers/views**: các điểm cuối (endpoints) API
- **Models/schemas**: các mô hình dữ liệu (Pydantic, SQLAlchemy, Django)
- **Services**: tầng logic nghiệp vụ
- **Repositories**: tầng truy cập dữ liệu
- **Migrations**: các bản di trú cơ sở dữ liệu Alembic, Django
- **Tasks**: Celery, các tác vụ chạy ngầm

## Nguồn câu lệnh
- Các mục cấu hình công cụ trong `pyproject.toml`
- README/docs, CI
- Phổ biến: `python manage.py`, `pytest`, `uvicorn`, `flask run`
- Chỉ đưa vào những câu lệnh thực sự tồn tại trong kho mã nguồn

## Các đường dẫn chính
- `src/`, `app/`
- `tests/`
- `alembic/`, `migrations/`
- `templates/`, `static/` (nếu là ứng dụng web)
FILE:references/react-native.md
# React Native

## Dấu hiệu nhận diện
- `package.json` có chứa `react-native`
- `metro.config.js`
- `app.json` hoặc `app.config.js` (Expo)
- Các thư mục `android/`, `ios/`
- `babel.config.js` có cấu hình metro preset

## Dấu hiệu đa mô-đun (Multi-module)
- Monorepo có thư mục `packages/`
- Nhiều tệp `app.json`
- Không gian làm việc Nx (Nx workspace) có sử dụng React Native

## Nguồn phân tích trước khi tạo
- `package.json` (các gói phụ thuộc, scripts)
- `app.json` hoặc `app.config.js`
- `metro.config.js`
- `babel.config.js`
- `tsconfig.json`

## Các mẫu quét kho mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `src/`, `app/`

### Các mẫu tầng/thư mục (ghi nhận nếu có mặt)
`screens/`, `components/`, `navigation/`, `services/`, `hooks/`, `store/`, `api/`, `utils/`, `assets/`

### Các chỉ báo mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Phát hiện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| Screen | `*Screen`, `export function *Screen` | rn-screen |
| Component | `export function *()`, `StyleSheet.create` | rn-component |
| Navigation | `createNativeStackNavigator`, `NavigationContainer` | rn-navigation |
| Hook | `use*`, `export function use*()` | rn-hook |
| Redux | `createSlice`, `configureStore` | redux-slice |
| Zustand | `create(`, `useStore` | zustand-store |
| React Query | `useQuery`, `useMutation` | react-query |
| Native Module | `NativeModules`, `TurboModule` | native-module |
| Async Storage | `AsyncStorage`, `@react-native-async-storage` | async-storage |
| SQLite | `expo-sqlite`, `react-native-sqlite-storage` | sqlite-storage |
| Push Notification | `@react-native-firebase/messaging`, `expo-notifications` | push-notification |
| Deep Link | `Linking`, `useURL`, `expo-linking` | deep-link |
| Animation | `Animated`, `react-native-reanimated` | rn-animation |
| Gesture | `react-native-gesture-handler`, `Gesture` | rn-gesture |
| Testing | `@testing-library/react-native`, `render` | rntl-test |

## Các phần đầu ra bắt buộc

Đưa vào nếu phát hiện thấy:
- **Danh mục màn hình (Screens inventory)**: các thư mục con nằm dưới `screens/`
- **Cấu trúc điều hướng (Navigation structure)**: các bộ điều hướng stack, tab, drawer
- **Quản lý trạng thái (State management)**: Redux, Zustand, Context
- **Mô-đun bản địa (Native modules)**: mã nguồn native tùy chỉnh
- **Tầng lưu trữ (Storage layer)**: AsyncStorage, SQLite, MMKV
- **Đặc thù theo nền tảng (Platform-specific)**: `*.android.tsx`, `*.ios.tsx`

## Nguồn câu lệnh
- Mục scripts trong `package.json`
- README/docs
- Phổ biến: `npm run android`, `npm run ios`, `npx expo start`
- Chỉ đưa vào những câu lệnh thực sự tồn tại trong kho mã nguồn

## Các đường dẫn chính
- `src/screens/`, `src/components/`
- `src/navigation/`, `src/store/`
- `android/app/`, `ios/*/`
- `assets/`
FILE:references/react-web.md
# React (Web)

## Dấu hiệu nhận diện
- `package.json` có chứa `react`, `react-dom`
- `vite.config.ts`, `next.config.js`, `craco.config.js`
- `tsconfig.json` hoặc `jsconfig.json`
- `src/App.tsx` hoặc `src/App.jsx`
- `public/index.html` (CRA)

## Dấu hiệu đa mô-đun (Multi-module)
- `pnpm-workspace.yaml`, `lerna.json`
- Nhiều tệp `package.json` trong các thư mục con
- Các thư mục `packages/`, `apps/`
- Không gian làm việc Nx (`nx.json`)

## Nguồn phân tích trước khi tạo
- `package.json` (các gói phụ thuộc, scripts)
- `tsconfig.json` (đường dẫn paths, tùy chọn trình biên dịch)
- `vite.config.*`, `next.config.*`, `webpack.config.*`
- `.env.example` (các biến môi trường)

## Các mẫu quét kho mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `src/`, `app/`, `pages/`

### Các mẫu tầng/thư mục (ghi nhận nếu có mặt)
`components/`, `hooks/`, `services/`, `utils/`, `store/`, `api/`, `types/`, `contexts/`, `features/`, `layouts/`

### Các chỉ báo mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Phát hiện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| Component | `export function *()`, `export const * =` có chứa JSX | react-component |
| Hook | `use*`, `export function use*()` | custom-hook |
| Context | `createContext`, `useContext`, `*Provider` | react-context |
| Redux | `createSlice`, `configureStore`, `useSelector` | redux-slice |
| Zustand | `create(`, `useStore` | zustand-store |
| React Query | `useQuery`, `useMutation`, `QueryClient` | react-query |
| Form | `useForm`, `react-hook-form`, `Formik` | form-handling |
| Router | `createBrowserRouter`, `Route`, `useNavigate` | react-router |
| API Client | `axios`, `fetch`, `ky` | api-client |
| Testing | `@testing-library/react`, `render`, `screen` | rtl-test |
| Storybook | `*.stories.tsx`, `Meta`, `StoryObj` | storybook |
| Styled | `styled-components`, `@emotion`, `styled(` | styled-component |
| Tailwind | `className="*"`, `tailwind.config.js` | tailwind-usage |
| i18n | `useTranslation`, `i18next`, `t()` | i18n-usage |
| Auth | `useAuth`, `AuthProvider`, `PrivateRoute` | auth-pattern |

## Các phần đầu ra bắt buộc

Đưa vào nếu phát hiện thấy:
- **Danh mục thành phần (Components inventory)**: các thư mục con dưới `components/`
- **Tính năng/trang (Features/pages)**: các thư mục con dưới `features/`, `pages/`
- **Quản lý trạng thái (State management)**: Redux, Zustand, Context
- **Thiết lập định tuyến (Routing setup)**: React Router, các trang Next.js
- **Tầng API (API layer)**: các thực thể axios, hàm bọc fetch
- **Phương pháp định kiểu (Styling approach)**: CSS modules, Tailwind, styled-components
- **Xử lý biểu mẫu (Form handling)**: react-hook-form, Formik

## Nguồn câu lệnh
- Mục scripts trong `package.json`
- README/docs
- Các luồng công việc CI (CI workflows)
- Phổ biến: `npm run dev`, `npm run build`, `npm test`
- Chỉ đưa vào những câu lệnh thực sự tồn tại trong kho mã nguồn

## Các đường dẫn chính
- `src/components/`, `src/hooks/`
- `src/pages/`, `src/features/`
- `src/store/`, `src/api/`
- `public/`, `dist/`, `build/`
FILE:references/ruby.md
# Ruby/Rails

## Dấu hiệu nhận diện
- `Gemfile`
- `Gemfile.lock`
- `config.ru`
- `Rakefile`
- `config/application.rb` (Rails)

## Dấu hiệu đa mô-đun (Multi-module)
- Nhiều tệp `Gemfile` trong các thư mục con
- Thư mục `engines/` (Rails engines)
- Thư mục `gems/` (monorepo)

## Nguồn phân tích trước khi tạo
- `Gemfile` (các gói phụ thuộc)
- `config/database.yml`
- `config/routes.rb` (Rails)
- `.env.example`

## Các mẫu quét kho mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `app/`, `lib/`

### Các mẫu tầng/thư mục (ghi nhận nếu có mặt)
`controllers/`, `models/`, `services/`, `jobs/`, `mailers/`, `channels/`, `helpers/`, `concerns/`

### Các chỉ báo mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Phát hiện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| Rails Controller | `< ApplicationController`, `def index` | rails-controller |
| Rails Model | `< ApplicationRecord`, `has_many`, `belongs_to` | rails-model |
| Rails Migration | `< ActiveRecord::Migration`, `create_table` | rails-migration |
| Service Object | `class *Service`, `def call` | service-object |
| Rails Job | `< ApplicationJob`, `perform_later` | rails-job |
| Mailer | `< ApplicationMailer`, `mail(` | rails-mailer |
| Channel | `< ApplicationCable::Channel` | action-cable |
| Serializer | `< ActiveModel::Serializer`, `attributes` | serializer |
| Concern | `extend ActiveSupport::Concern` | rails-concern |
| Sidekiq Worker | `include Sidekiq::Worker`, `perform_async` | sidekiq-worker |
| Grape API | `Grape::API`, `resource :` | grape-api |
| RSpec Test | `RSpec.describe`, `it "` | rspec-test |
| Factory | `FactoryBot.define`, `factory :` | factory-bot |
| Rake Task | `task :`, `namespace :` | rake-task |

## Các phần đầu ra bắt buộc

Đưa vào nếu phát hiện thấy:
- **Controllers**: các điểm cuối (endpoints) HTTP
- **Models**: các mối quan hệ liên kết ActiveRecord
- **Services**: logic nghiệp vụ
- **Jobs**: xử lý tác vụ chạy ngầm
- **Migrations**: lược đồ cơ sở dữ liệu

## Nguồn câu lệnh
- Các script trong `Gemfile`
- Các tác vụ trong `Rakefile`
- `bin/rails`, `bin/rake`
- README/docs, CI
- Chỉ đưa vào những câu lệnh thực sự tồn tại trong kho mã nguồn

## Các đường dẫn chính
- `app/controllers/`, `app/models/`
- `app/services/`, `app/jobs/`
- `db/migrate/`
- `spec/`, `test/`
- `lib/`
FILE:references/rust.md
# Rust

## Dấu hiệu nhận diện
- `Cargo.toml`
- `Cargo.lock`
- `src/main.rs` hoặc `src/lib.rs`
- Thư mục `target/`

## Dấu hiệu đa mô-đun (Multi-module)
- `[workspace]` trong `Cargo.toml`
- Nhiều tệp `Cargo.toml` trong các thư mục con
- Các thư mục `crates/`, `packages/`

## Nguồn phân tích trước khi tạo
- `Cargo.toml` (các gói phụ thuộc, tính năng features)
- `build.rs` (script biên dịch)
- `rust-toolchain.toml` (bộ công cụ toolchain)

## Các mẫu quét kho mã nguồn (Codebase scan patterns)

### Thư mục mã nguồn gốc (Source roots)
- `src/`, `crates/*/src/`

### Các mẫu tầng/thư mục (ghi nhận nếu có mặt)
`handlers/`, `services/`, `models/`, `db/`, `api/`, `utils/`, `error/`, `config/`

### Các chỉ báo mẫu (Pattern indicators)

| Mẫu (Pattern) | Tiêu chí Phát hiện | Tên Kỹ năng (Skill Name) |
|---------|-------------------|------------|
| Axum Handler | `axum::`, `Router`, `async fn handler` | axum-handler |
| Actix Route | `actix_web::`, `#[get]`, `#[post]` | actix-route |
| Rocket Route | `rocket::`, `#[get]`, `#[post]` | rocket-route |
| Service | `impl *Service`, `pub struct *Service` | rust-service |
| Repository | `*Repository`, `trait *Repository` | rust-repository |
| Diesel Model | `diesel::`, `Queryable`, `Insertable` | diesel-model |
| SQLx | `sqlx::`, `FromRow`, `query_as!` | sqlx-model |
| SeaORM | `sea_orm::`, `Entity`, `ActiveModel` | seaorm-entity |
| Error Type | `thiserror`, `anyhow`, `#[derive(Error)]` | error-type |
| CLI | `clap`, `#[derive(Parser)]` | cli-app |
| Async Task | `tokio::spawn`, `async fn` | async-task |
| Trait | `pub trait *`, `impl * for` | rust-trait |
| Unit Test | `#[cfg(test)]`, `#[test]` | rust-test |
| Integration Test | `tests/`, `#[tokio::test]` | integration-test |

## Các phần đầu ra bắt buộc

Đưa vào nếu phát hiện thấy:
- **Handlers/routes**: các điểm cuối (endpoints) API
- **Services**: logic nghiệp vụ
- **Models/entities**: các cấu trúc dữ liệu
- **Kiểu lỗi (Error types)**: các kiểu lỗi tùy chỉnh
- **Migrations**: các bản di trú dữ liệu diesel/sqlx

## Nguồn câu lệnh
- Các script/bí danh (aliases) trong `Cargo.toml`
- `Makefile`, README/docs
- Phổ biến: `cargo build`, `cargo test`, `cargo run`
- Chỉ đưa vào những câu lệnh thực sự tồn tại trong kho mã nguồn

## Các đường dẫn chính
- `src/`, `crates/`
- `tests/`
- `migrations/`
- `examples/`

Claude Agent Infrastructure+2

B@barisatalay