Prompt Creator

---
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()

---
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/`

---
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/`