Cách Sử Dụng Kỹ Năng Code Của Claude Để Viết Tài Liệu

Herve Kom

22 tháng 1 2026

Cách Sử Dụng Kỹ Năng Code Của Claude Để Viết Tài Liệu

Nếu bạn từng phải tiếp nhận tài liệu không đầy đủ, không nhất quán và đã lỗi thời, bạn sẽ hiểu vấn đề: các nhóm tạo tài liệu với ý định tốt, nhưng nếu không có quy trình đánh giá nghiêm ngặt, sự rõ ràng sẽ bị xói mòn. Các tham số API không được ghi lại. Các phản hồi lỗi thiếu hướng dẫn. Các ví dụ bị hỏng một cách âm thầm. Thuật ngữ bị trôi dạt giữa các tệp.

💡
Tài liệu kỹ thuật đang làm bạn chậm lại? Kết hợp Claude Code với Apidog để có được phạm vi tài liệu đầy đủ: đánh giá văn xuôi bằng AI + xác thực API trực quan. Hãy dùng thử miễn phí cả hai: claude.ai và apidog.com. Lập tài liệu thông minh hơn.

Kỹ năng Claude Code giải quyết vấn đề này một cách có hệ thống. Các quy trình làm việc được hỗ trợ bởi AI này xem xét toàn bộ kho lưu trữ tài liệu của bạn, xác định các lỗ hổng và sự không nhất quán, đồng thời áp dụng các bản sửa lỗi trực tiếp. Bạn mô tả những gì cần xem xét, và Claude sẽ tạo ra một bản kiểm tra có cấu trúc, áp dụng các cải tiến và xác thực tính đầy đủ, tất cả đều từ thiết bị đầu cuối của bạn.

Tài liệu kỹ thuật bao gồm các thông số kỹ thuật API, hướng dẫn sử dụng, hướng dẫn triển khai và ghi chú phát hành. Claude Code tự động hóa việc xem xét tất cả các tài liệu này. Đối với tài liệu API nói riêng, hãy kết hợp nó với Apidog để xác thực trực quan và chấm điểm tính đầy đủ.

Tìm hiểu Kỹ năng Claude Code dành cho Tài liệu

Kỹ năng Tài liệu là gì?

Kỹ năng Claude Code là các quy trình làm việc AI tùy chỉnh, có thể tái sử dụng, mở rộng khả năng tài liệu của Claude Code. Hãy hình dung chúng như những kiểm toán viên tài liệu thông minh có thể:

Không giống như các công cụ kiểm tra cú pháp truyền thống (linters), các kỹ năng này tận dụng khả năng suy luận của Claude để hiểu các vấn đề ngữ nghĩa — mô tả mơ hồ, tài liệu lỗi còn thiếu, ví dụ không nhất quán.

Cách Kỹ năng hoạt động

Các kỹ năng hoạt động thông qua một số cơ chế:

1. Lệnh có thể gọi bởi người dùng

# Run a skill with a slash command
/review-docs --completeness
/check-consistency --terminology
/validate-api-specs
/update-broken-examples

2. Công cụ được phép

Các kỹ năng chỉ định những công cụ mà chúng có thể sử dụng:

3. Tệp Kế hoạch

Các kỹ năng duy trì trạng thái bằng cách sử dụng các tệp markdown để theo dõi tiến độ đánh giá, các vấn đề được xác định và các bản sửa lỗi đã áp dụng.

Tại sao Kỹ năng vượt trội trong việc đánh giá tài liệu

Việc đánh giá tài liệu truyền thống là thủ công và không nhất quán. Các kỹ năng mang lại trí thông minh và khả năng mở rộng:

Các khả năng đánh giá tài liệu cốt lõi

1. Phân tích tính đầy đủ

Yêu cầu: "Kiểm tra tài liệu API về tính đầy đủ. Kiểm tra từng điểm cuối (endpoint) về: các tham số, ví dụ yêu cầu, tất cả các phản hồi lỗi và giới hạn tốc độ."

Claude tạo ra:

Missing from POST /users endpoint:
- [ ] Request body parameter descriptions
- [ ] Error response documentation (400, 401, 409)
- [ ] Rate limiting information
- [ ] Security/authentication requirements

2. Phát hiện sự nhất quán

Yêu cầu: "Xem xét /docs/ để kiểm tra tính nhất quán của thuật ngữ. Gắn cờ bất kỳ thuật ngữ nào xuất hiện nhiều lần với các ý nghĩa khác nhau."

Claude xác định:

Inconsistent terminology found:
- "API key" vs "access token" vs "auth token" (use one)
- "endpoint" vs "route" vs "method" (use one)
- "user object" vs "user resource" (use one)

3. Xác thực đối chiếu

Yêu cầu: "So sánh thông số kỹ thuật OpenAPI trong /api/openapi.yaml với tài liệu trong /docs/api/. Gắn cờ bất kỳ điểm cuối nào trong mã không được ghi lại hoặc được ghi lại nhưng không có trong mã."

Claude phát hiện:

Discrepancies found:
- POST /api/webhooks documented but not in openapi.yaml
- PATCH /api/users exists in code but missing from docs
- Response schema changed but example not updated

4. Đánh giá sự rõ ràng

Yêu cầu: "Xem xét về sự rõ ràng. Gắn cờ các mô tả mơ hồ, thuật ngữ không xác định và hướng dẫn không rõ ràng."

Claude xác định:

Clarity issues:
- Line 45: "Set config to appropriate values" - what values?
- Line 120: "user object" used without schema definition
- Line 200: "required fields" - which ones?

5. Xác thực ví dụ

Yêu cầu: "Xem xét tất cả các ví dụ mã. Kiểm tra chúng dựa trên lược đồ API hiện tại. Gắn cờ các ví dụ bị hỏng hoặc lỗi thời."

Claude cập nhật:

Updated examples:
- curl example: Response format changed, updated payload
- Python example: Using deprecated parameter, fixed
- JavaScript example: Missing error handling, added

Giải phẫu của một Kỹ năng Tài liệu

Cấu trúc thư mục

Các kỹ năng tài liệu nằm trong .claude/skills/ với cấu trúc này:

.claude/
├── skills/
│   ├── docs-completeness/
│   │   ├── SKILL.md              # Skill manifest
│   │   ├── planning.md           # Review progress
│   │   └── criteria.md           # Quality checklist
│   ├── api-validation/
│   │   ├── SKILL.md
│   │   └── schemas/              # API schemas
│   └── consistency-check/
│       └── SKILL.md
└── skills.md                     # Index of all skills

Tệp SKILL.md Manifest

Mỗi kỹ năng tài liệu đều bắt đầu bằng phần đầu YAML (frontmatter):

---
name: docs-completeness
version: "1.0.0"
description: Review documentation for completeness and clarity
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Grep
  - Glob
  - Edit
hooks:
  SessionStart:
    - matcher: command
      command: "echo '[Docs Review] Starting documentation audit...'"
  Stop:
    - matcher: command
      command: "echo '[Docs Review] Audit complete. Review findings above.'"
---

# Kỹ năng Hoàn chỉnh Tài liệu

Xem xét tài liệu kỹ thuật về tính đầy đủ và rõ ràng.

## Cách sử dụng

```bash
/docs-completeness                # Kiểm tra toàn bộ kho lưu trữ
/docs-completeness --api-only    # Chỉ tài liệu API
/docs-completeness --section api/endpoints.md  # Tệp cụ thể

Hướng dẫn cho Claude

Khi được gọi:

  1. Phát hiện phạm vi → Xác định các tệp mục tiêu hoặc toàn bộ kho lưu trữ
  2. Phân tích tính đầy đủ → Kiểm tra từng phần so với danh sách kiểm tra
  3. Thu thập vấn đề → Tập hợp tất cả các vấn đề với vị trí
  4. Ưu tiên → Sắp xếp theo tác động (thiếu sót so với không rõ ràng so với không nhất quán)
  5. Tạo báo cáo → Xuất các phát hiện có cấu trúc
  6. Đề xuất sửa lỗi → Đưa ra các cải tiến cụ thể
  7. Xác thực → Xác minh các bản sửa lỗi trước khi áp dụng

Tạo Kỹ năng Tài liệu đầu tiên của bạn

Thực hành ngay: Chúng ta sẽ xây dựng một công cụ tiện dụng để kiểm tra tài liệu API về các lỗ hổng, đảm bảo chúng đầy đủ và sẵn sàng cho nhà phát triển. Hãy coi nó như người thực thi tài liệu cá nhân của bạn.

Bước 1: Thiết lập thư mục Kỹ năng

Khởi tạo cấu trúc bằng một lệnh đơn giản — các kỹ năng của Claude nằm ở một vị trí chuyên dụng để dễ dàng khám phá.

Bash

mkdir -p .claude/skills/api-docs-review

Bước 2: Viết Manifest của Kỹ năng

Tạo tệp .claude/skills/api-docs-review/SKILL.md:

---
name: api-docs-review
version: "1.0.0"
description: Review API documentation for completeness
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Grep
  - Edit
---

# Kỹ năng Đánh giá Tài liệu API

Kiểm tra tài liệu API về tính đầy đủ, rõ ràng và chính xác.

## Tiêu chí Đánh giá

Mỗi điểm cuối phải có:

**Thông tin Cơ bản**
* Mô tả rõ ràng về chức năng của điểm cuối
* Phương thức HTTP và đường dẫn
* Yêu cầu xác thực

**Tài liệu Yêu cầu**
* Tất cả các tham số đường dẫn với kiểu và mô tả
* Tất cả các tham số truy vấn với giá trị mặc định và ràng buộc
* Lược đồ phần thân yêu cầu (đối với POST/PUT/PATCH)
* Yêu cầu về tiêu đề Content-Type
* Ví dụ yêu cầu (curl hoặc ngôn ngữ cụ thể)

**Tài liệu Phản hồi**
* Phản hồi thành công (200/201) với lược đồ và ví dụ
* Tất cả các phản hồi lỗi (400, 401, 403, 404, 409, 429, 500) với ví dụ
* Thông tin giới hạn tốc độ
* Các tiêu đề phản hồi (nếu có liên quan)

**Bổ sung**
* Các điểm cuối hoặc hướng dẫn liên quan
* Lịch sử phiên bản nếu áp dụng
* Cảnh báo không dùng nữa (nếu đã bị loại bỏ)

## Hướng dẫn

Khi được gọi:

1. **Quét các tệp điểm cuối** trong /docs/api/
2. **Kiểm tra từng điểm cuối** theo tiêu chí đánh giá
3. **Ghi lại các mục còn thiếu** với các tham chiếu tệp/dòng cụ thể
4. **Xác định các vấn đề về độ rõ ràng** (mô tả mơ hồ, thuật ngữ không xác định)
5. **Gắn cờ các vấn đề về tính nhất quán** (trôi dạt thuật ngữ, khác biệt định dạng)
6. **Tạo danh sách kiểm tra** các bản sửa lỗi cần thiết
7. **Đề nghị áp dụng các bản sửa lỗi** với các ví dụ

Định dạng báo cáo:

ĐIỂM CUỐI: POST /api/users Tệp: docs/api/users.md Trạng thái: Hoàn thành 65%

Còn thiếu:

Vấn đề:

Các bản sửa lỗi có sẵn: Có (yêu cầu áp dụng)

Bước 3: Đăng ký Kỹ năng

Thêm vào tệp .claude/skills.md:

# Các Kỹ năng Tài liệu có sẵn

## Tài liệu API

### /api-docs-review
Kiểm tra tài liệu API về tính đầy đủ theo các tiêu chí chuẩn.
- **Phiên bản**: 1.0.0
- **Sử dụng**: `/api-docs-review [--file PATH] [--endpoint NAME]`
- **Khi nào nên sử dụng**: Trước khi phát hành API, sau khi thay đổi mã
- **Thời gian**: 5-10 phút cho API cỡ trung bình

Bước 4: Kiểm tra Kỹ năng

# In Claude Code
/api-docs-review

Claude giờ đây sẽ kiểm tra tài liệu API của bạn một cách có hệ thống.

Các Mẫu Tài liệu Nâng cao

Mẫu 1: Theo dõi Tài liệu theo Phiên bản

Các kỹ năng có thể theo dõi chất lượng tài liệu qua các phiên bản:

## Lịch sử Phiên bản

### v2.0.0 [2026-01-22]
Hoàn chỉnh: 95% ✅
- Tất cả các điểm cuối đã được ghi lại
- Phản hồi lỗi đầy đủ
- Các ví dụ đã được cập nhật
- Các điểm cuối /v1 đã lỗi thời được đánh dấu

### v1.0.0 [2025-12-01]
Hoàn chỉnh: 70%
- Thiếu tài liệu lỗi
- Các ví dụ lỗi thời
- Không có cảnh báo không dùng nữa

Claude phát hiện những cải tiến theo thời gian.

Mẫu 2: Xác thực Thông số kỹ thuật API so với Mã

Các kỹ năng có thể xác thực các thông số kỹ thuật OpenAPI khớp với việc triển khai:

## Xác thực Thông số kỹ thuật

So sánh /api/openapi.yaml với mã:

1. **Quét việc triển khai** cho tất cả các route
2. **Kiểm tra thông số kỹ thuật OpenAPI** cho mỗi route
3. **Gắn cờ các điểm cuối còn thiếu**
4. **Xác minh các tham số** khớp với việc triển khai
5. **Cập nhật các ví dụ** để khớp với lược đồ hiện tại

Kết quả: Thông số kỹ thuật đồng bộ 100% với mã

Tự động hóa với CI/CD

Quy trình xác thực tài liệu

Thiết lập các kiểm tra tự động cho mỗi lần cập nhật tài liệu:

# .github/workflows/docs-check.yml
name: Kiểm tra Tài liệu

on:
  push:
    paths:
      - 'docs/**'
      - 'api/openapi.yaml'
  pull_request:
    paths:
      - 'docs/**'
      - 'api/openapi.yaml'

jobs:
  validate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Cài đặt Apidog CLI
        run: npm install -g apidog-cli

      - name: Xác thực Thông số kỹ thuật OpenAPI
        run: |
          apidog lint api/openapi.yaml
          apidog check-completeness api/openapi.yaml --min-score 85

      - name: Kiểm tra các liên kết hỏng
        run: |
          npm install -g markdown-link-check
          find docs -name "*.md" -exec markdown-link-check {} \;

      - name: Xác minh các ví dụ hợp lệ
        run: |
          # Kiểm tra các ví dụ curl hoạt động
          bash scripts/test-curl-examples.sh

      - name: Bình luận trên PR
        if: failure()
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '❌ Xác thực tài liệu thất bại. Hãy xem lại nhật ký luồng công việc.'
            })

Tình huống Thực tế: Tính đầy đủ của Tài liệu API

Hãy cùng kiểm tra một bộ tài liệu API thực tế về tính đầy đủ và áp dụng các cải tiến.

Tình huống

Bạn có tài liệu REST API đã 6 tháng tuổi. Nó chỉ hoàn thiện một phần nhưng thiếu tài liệu về lỗi, không rõ ràng ở một số chỗ và có các ví dụ lỗi thời.

Kiểm tra

Yêu cầu gửi đến Claude: "Kiểm tra tài liệu trong /docs/api/. Đối với mỗi điểm cuối, hãy kiểm tra: mô tả, tham số yêu cầu, ví dụ phản hồi và tất cả các phản hồi lỗi. Ưu tiên các bản sửa lỗi theo mức độ tác động."

KẾT QUẢ KIỂM TRA
=============

NGHIÊM TRỌNG (Thiếu tài liệu lỗi):
├── POST /api/users - Thiếu phản hồi lỗi 400, 401, 409
├── POST /api/auth/login - Thiếu phản hồi 429 (giới hạn tốc độ)
└── DELETE /api/resources/{id} - Thiếu phản hồi 403 (bị cấm)

CAO (Vấn đề rõ ràng):
├── users.md:45 - "đối tượng người dùng" không xác định
├── auth.md:60 - "Đặt thời hạn hết hiệu lực thành giá trị phù hợp" - quá mơ hồ
└── resources.md:30 - Thiếu mô tả định dạng con trỏ phân trang

TRUNG BÌNH (Ví dụ lỗi thời):
├── products.md:120 - Ví dụ cURL trả về định dạng cũ
├── orders.md:80 - Ví dụ Python SDK sử dụng tham số đã lỗi thời
└── webhooks.md:60 - Ví dụ Node.js thiếu xử lý lỗi

NHẤT QUÁN:
├── "khóa API" vs "mã truy cập" - 5 trường hợp không nhất quán
├── Định dạng phần thân yêu cầu - 3 kiểu khác nhau giữa các điểm cuối
└── Lược đồ phản hồi lỗi - 2 biến thể thay vì 1

Sửa lỗi ưu tiên: Tổng cộng 15
Ước tính công sức: 2-3 giờ thủ công, 15 phút với Claude Code

Các Cải tiến

Áp dụng các bản sửa lỗi một cách có hệ thống:

Trước - POST /api/users (Chưa hoàn chỉnh):

## Tạo Người dùng

POST /api/users

Tạo một người dùng mới.

**Tham số:**
- name: Tên người dùng
- email: Email người dùng

**Phản hồi:**
```json
{
  "id": "usr_123",
  "name": "Alice",
  "email": "alice@example.com"
}

**Sau - POST /api/users (Hoàn chỉnh):**
```markdown
## Tạo Người dùng

`POST /api/users`

Tạo một tài khoản người dùng mới với các chi tiết được cung cấp. Email phải là duy nhất.

### Xác thực

Yêu cầu khóa API trong tiêu đề `Authorization`: `Bearer YOUR_API_KEY`

### Tham số Yêu cầu

| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
| `name` | string | Có | Tên đầy đủ (2-100 ký tự) |
| `email` | string | Có | Email hợp lệ (phải là duy nhất) |
| `role` | string | Không | Vai trò: `admin`, `developer`, `viewer`. Mặc định: `viewer` |

### Ví dụ Yêu cầu

```bash
curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice Smith",
    "email": "alice@example.com",
    "role": "developer"
  }'

Phản hồi (201 Created)

{
  "id": "usr_abc123",
  "name": "Alice Smith",
  "email": "alice@example.com",
  "role": "developer",
  "created_at": "2026-01-22T10:30:00Z"
}

Phản hồi lỗi

400 Bad Request - Đầu vào không hợp lệ

{
  "error": "validation_error",
  "message": "Invalid email format",
  "field": "email",
  "request_id": "req_xyz789"
}

401 Unauthorized - Khóa API bị thiếu/không hợp lệ

{
  "error": "unauthorized",
  "message": "Invalid API key",
  "request_id": "req_xyz789"
}

409 Conflict - Email đã tồn tại

{
  "error": "conflict",
  "message": "User with this email already exists",
  "request_id": "req_xyz789"
}

429 Too Many Requests - Bị giới hạn tốc độ

{
  "error": "rate_limited",
  "message": "Too many requests. Try again in 60 seconds.",
  "retry_after": 60,
  "request_id": "req_xyz789"
}

Giới hạn tốc độ

100 yêu cầu mỗi phút cho mỗi khóa API. Xem Giới hạn Tốc độ.


**Các cải tiến đã áp dụng:**
- Đã thêm các yêu cầu xác thực
- Đã ghi lại tất cả các tham số với các ràng buộc
- Phản hồi thành công hoàn chỉnh + tất cả các phản hồi lỗi
- Ví dụ cURL sẵn sàng cho sản xuất
- Thông tin giới hạn tốc độ
- Định dạng nhất quán

Tích hợp Claude với Apidog để có Tài liệu API Vượt trội

💡 Mẹo Chuyên Nghiệp: Tận dụng Claude để đánh giá chuyên sâu các tài liệu tường thuật, trong khi Apidog đảm bảo các thông số kỹ thuật API của bạn vững chắc và tự động điền vào các khoảng trống bằng các ví dụ thực tế.

Yêu cầu đề xuất cho Claude:"Kiểm tra /docs/api/ về độ rõ ràng và mức độ tương tác tổng thể. Tiếp theo, đối chiếu tính đầy đủ của tệp /api/openapi.yaml bằng cách sử dụng Apidog. Nêu bật bất kỳ sự không nhất quán hoặc các yếu tố còn thiếu nào, để tôi có thể xử lý chúng trực tiếp trong Apidog trước khi tiếp tục."

Bash

# Bước 1: Đánh giá văn xuôi ban đầu qua Claude
> /docs-completeness  # Xuất các đề xuất để có ngôn ngữ và cấu trúc rõ ràng hơn

# Bước 2: Xác thực thông số kỹ thuật API trong Apidog
apidog check-completeness api/openapi.yaml  # Gắn cờ các vấn đề như lược đồ không đầy đủ hoặc phản hồi còn thiếu

# Bước 3: Tự động tạo nội dung bằng AI của Apidog
# (Qua giao diện người dùng Apidog: Cài đặt → AI → Tự động tạo mô tả, ví dụ và tóm tắt)

# Bước 4: Kiểm tra sự hài hòa cuối cùng với Claude
> /consistency-check  # Đảm bảo tài liệu và thông số kỹ thuật được căn chỉnh hoàn hảo

Điều này tạo ra một quy trình làm việc trong đó Apidog xử lý việc xác thực thông số kỹ thuật có cấu trúc và Claude Code xử lý chất lượng văn xuôi.

Thực tiễn tốt nhất để Đánh giá Tài liệu

Biết đối tượng của bạn

Điều chỉnh độ sâu tài liệu cho phù hợp với người đọc:

Đối tượng Phong cách Ví dụ
Nhà phát triển Ví dụ mã bằng nhiều ngôn ngữ cURL, Python, JS
DevOps Các bước triển khai, cấu hình Ví dụ Kubernetes YAML
Nhóm sản phẩm Quy trình làm việc cấp cao, sơ đồ Luồng tính năng với ảnh chụp màn hình
Hỗ trợ Khắc phục sự cố, các vấn đề thường gặp "Lỗi 429 có nghĩa là..."

Ưu tiên sự rõ ràng

Viết bằng thể chủ động, cấu trúc để dễ dàng quét qua:

❌ Trước: "Yêu cầu được gửi qua POST. Phản hồi sẽ chứa người dùng."
✅ Sau: "Gửi một yêu cầu POST để tạo người dùng. API sẽ trả về người dùng mới."

Luôn bao gồm ví dụ

Các khái niệm trừu tượng cần được neo giữ. Mỗi điểm cuối API cần:

# ✅ Sẵn sàng sao chép-dán
curl -X GET https://api.example.com/v1/users/usr_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Những cạm bẫy thường gặp

Cạm bẫy Giải pháp
Quá nhiều thuật ngữ chuyên ngành Định nghĩa thuật ngữ khi sử dụng lần đầu
Ví dụ lỗi thời Kiểm tra trong CI/CD
Thiếu tài liệu lỗi Ghi lại tất cả các mã lỗi
Định dạng không nhất quán Sử dụng mẫu
Liên kết hỏng Kiểm tra trong CI/CD

Kết luận

Kỹ năng Claude Code biến đổi việc xem xét tài liệu kỹ thuật từ một quy trình thủ công tẻ nhạt thành một quy trình làm việc thông minh, tự động. Bạn mô tả những gì cần xem xét, và Claude sẽ kiểm tra toàn bộ kho lưu trữ tài liệu của bạn, xác định các lỗ hổng và sự không nhất quán, đồng thời áp dụng các bản sửa lỗi, tất cả trong khi vẫn duy trì các tiêu chuẩn chất lượng.

Kết hợp với Apidog để xác thực thông số kỹ thuật API, bạn sẽ đạt được phạm vi tài liệu toàn diện.

button

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API