Jika Anda pernah mewarisi dokumentasi yang tidak lengkap, tidak konsisten, dan usang, Anda tahu masalahnya: tim membuat dokumen dengan niat baik, tetapi tanpa tinjauan yang ketat, kejelasan akan memudar. Parameter API tidak terdokumentasi. Respons kesalahan tidak memiliki panduan. Contoh rusak secara diam-diam. Terminologi bergeser antar file.
Claude Code Skills menyelesaikan masalah ini secara sistematis. Alur kerja bertenaga AI ini meninjau seluruh repositori dokumentasi Anda, mengidentifikasi celah dan inkonsistensi, serta menerapkan perbaikan secara langsung. Anda menjelaskan apa yang perlu ditinjau, dan Claude menghasilkan audit terstruktur, menerapkan perbaikan, dan memvalidasi kelengkapan semuanya dari terminal Anda.
Dokumentasi teknis mencakup spesifikasi API, panduan pengguna, panduan penerapan, dan catatan rilis. Claude Code mengotomatiskan peninjauan semuanya. Khusus untuk dokumentasi API, gabungkan dengan Apidog untuk validasi visual dan penilaian kelengkapan.
Memahami Claude Code Skills untuk Dokumentasi
Apa Itu Documentation Skills?
Claude Code Skills adalah alur kerja AI kustom yang dapat digunakan kembali yang memperluas kemampuan dokumentasi Claude Code. Anggaplah mereka sebagai auditor dokumentasi cerdas yang dapat:
- Membaca seluruh repositori dokumentasi Anda dan memahami konteks
- Melakukan referensi silang spesifikasi dengan implementasi dan panduan
- Mengidentifikasi bagian yang hilang, bahasa yang tidak jelas, dan inkonsistensi
- Menyarankan perbaikan spesifik dengan lokasi file dan nomor baris
- Menerapkan perbaikan langsung ke file Anda dan memvalidasi perubahan
Tidak seperti linter tradisional yang memeriksa sintaksis, skill memanfaatkan penalaran Claude untuk memahami masalah semantik deskripsi yang tidak jelas, dokumentasi kesalahan yang hilang, contoh yang tidak konsisten.
Bagaimana Skills Bekerja
Skills beroperasi melalui beberapa mekanisme:
1. Perintah yang Dapat Dipanggil Pengguna
# Jalankan skill dengan perintah slash
/review-docs --completeness
/check-consistency --terminology
/validate-api-specs
/update-broken-examples
2. Alat yang Diizinkan
Skills menentukan alat mana yang dapat mereka gunakan:
Bash: Menjalankan perintah validasiRead,Write,Edit: Mengelola file dokumentasiGlob,Grep: Mencari di seluruh dokumenWebFetch: Mengambil referensi eksternalTask: Membuat sub-tugas untuk tinjauan kompleks
3. File Perencanaan
Skills mempertahankan status menggunakan file markdown untuk melacak kemajuan tinjauan, masalah yang teridentifikasi, dan perbaikan yang diterapkan.
Mengapa Skills Unggul dalam Peninjauan Dokumentasi
Peninjauan dokumentasi tradisional bersifat manual dan tidak konsisten. Skills membawa kecerdasan dan skala:
- Pemahaman Holistik: Meninjau semua file, menangkap pola antar file
- Standar Konsisten: Menerapkan kriteria kualitas yang sama ke setiap file
- Saran Kontekstual: Memahami mengapa sesuatu salah, bukan hanya bahwa itu salah
- Otomatisasi: Dapat meninjau secara terus-menerus seiring berkembangnya dokumentasi
- Kecepatan: Menganalisis ratusan halaman dalam hitungan menit dibandingkan berjam-jam peninjauan manual
Kemampuan Peninjauan Dokumentasi Inti
1. Analisis Kelengkapan
Prompt: "Audit dokumentasi API untuk kelengkapannya. Periksa setiap endpoint untuk: parameter, contoh permintaan, semua respons kesalahan, dan pembatasan tingkat permintaan (rate limiting)."
Claude menghasilkan:
Hilang dari endpoint POST /users:
- [ ] Deskripsi parameter body permintaan
- [ ] Dokumentasi respons kesalahan (400, 401, 409)
- [ ] Informasi pembatasan tingkat permintaan (rate limiting)
- [ ] Persyaratan keamanan/autentikasi
2. Deteksi Konsistensi
Prompt: "Tinjau /docs/ untuk konsistensi terminologi. Tandai istilah apa pun yang muncul berkali-kali dengan arti yang berbeda."
Claude mengidentifikasi:
Terminologi tidak konsisten ditemukan:
- "API key" vs "access token" vs "auth token" (gunakan salah satu)
- "endpoint" vs "route" vs "method" (gunakan salah satu)
- "user object" vs "user resource" (gunakan salah satu)
3. Validasi Referensi Silang
Prompt: "Bandingkan spesifikasi OpenAPI di /api/openapi.yaml dengan dokumentasi di /docs/api/. Tandai endpoint mana pun dalam kode yang tidak didokumentasikan atau didokumentasikan tetapi tidak ada dalam kode."
Claude mendeteksi:
Ketidaksesuaian ditemukan:
- POST /api/webhooks didokumentasikan tetapi tidak ada di openapi.yaml
- PATCH /api/users ada dalam kode tetapi hilang dari dokumen
- Skema respons berubah tetapi contoh tidak diperbarui
4. Penilaian Kejelasan
Prompt: "Tinjau untuk kejelasan. Tandai deskripsi yang tidak jelas, istilah yang tidak terdefinisi, dan instruksi yang ambigu."
Claude mengidentifikasi:
Masalah kejelasan:
- Baris 45: "Atur konfigurasi ke nilai yang sesuai" - nilai apa?
- Baris 120: "objek pengguna" digunakan tanpa definisi skema
- Baris 200: "bidang yang diperlukan" - yang mana?
5. Validasi Contoh
Prompt: "Tinjau semua contoh kode. Uji terhadap skema API saat ini. Tandai contoh yang rusak atau usang."
Claude memperbarui:
Contoh yang diperbarui:
- Contoh curl: Format respons berubah, payload diperbarui
- Contoh Python: Menggunakan parameter usang, diperbaiki
- Contoh JavaScript: Penanganan kesalahan hilang, ditambahkan
Anatomi Documentation Skill
Struktur Direktori
Documentation skills berada di .claude/skills/ dengan tata letak ini:
.claude/
├── skills/
│ ├── docs-completeness/
│ │ ├── SKILL.md # Manifes skill
│ │ ├── planning.md # Progres peninjauan
│ │ └── criteria.md # Daftar periksa kualitas
│ ├── api-validation/
│ │ ├── SKILL.md
│ │ └── schemas/ # Skema API
│ └── consistency-check/
│ └── SKILL.md
└── skills.md # Indeks semua skill
Manifes SKILL.md
Setiap documentation skill dimulai dengan YAML frontmatter:
---
name: docs-completeness
version: "1.0.0"
description: Meninjau dokumentasi untuk kelengkapan dan kejelasan
user-invocable: true
allowed-tools:
- Read
- Write
- Grep
- Glob
- Edit
hooks:
SessionStart:
- matcher: command
command: "echo '[Docs Review] Memulai audit dokumentasi...'"
Stop:
- matcher: command
command: "echo '[Docs Review] Audit selesai. Tinjau temuan di atas.'"
---
# Skill Kelengkapan Dokumentasi
Meninjau dokumentasi teknis untuk kelengkapan dan kejelasan.
## Penggunaan
```bash
/docs-completeness # Audit repositori penuh
/docs-completeness --api-only # Hanya dokumen API
/docs-completeness --section api/endpoints.md # File spesifik
Instruksi untuk Claude
Saat dipanggil:
- Deteksi cakupan → Menentukan file target atau repositori penuh
- Analisis kelengkapan → Memeriksa setiap bagian terhadap daftar periksa
- Pengumpulan masalah → Mengumpulkan semua masalah dengan lokasi
- Prioritisasi → Mengurutkan berdasarkan dampak (hilang vs. tidak jelas vs. tidak konsisten)
- Pembuatan laporan → Mengeluarkan temuan terstruktur
- Saran perbaikan → Menawarkan peningkatan spesifik
- Validasi → Memverifikasi perbaikan sebelum menerapkan
Membuat Documentation Skill Pertama Anda
Selami secara langsung: Kita akan membuat alat praktis untuk mengaudit dokumen API dari celah, memastikan dokumen tersebut komprehensif dan siap untuk pengembang. Anggap saja sebagai penegak dokumen pribadi Anda.
Langkah 1: Siapkan Folder Skill
Bootstrap struktur dengan perintah sederhana Skill Claude berada di tempat khusus agar mudah ditemukan.
Bash
mkdir -p .claude/skills/api-docs-reviewLangkah 2: Tulis Manifes Skill
Buat .claude/skills/api-docs-review/SKILL.md:
---
name: api-docs-review
version: "1.0.0"
description: Meninjau dokumentasi API untuk kelengkapan
user-invocable: true
allowed-tools:
- Read
- Write
- Grep
- Edit
---
# Skill Peninjauan Dokumentasi API
Mengaudit dokumentasi API untuk kelengkapan, kejelasan, dan akurasi.
## Kriteria Peninjauan
Setiap endpoint harus memiliki:
**Informasi Dasar**
* Deskripsi jelas tentang apa yang dilakukan endpoint
* Metode HTTP dan jalur
* Persyaratan autentikasi
**Dokumentasi Permintaan**
* Semua parameter jalur dengan tipe dan deskripsi
* Semua parameter kueri dengan nilai default dan batasan
* Skema body permintaan (untuk POST/PUT/PATCH)
* Persyaratan header Content-Type
* Contoh permintaan (curl atau spesifik bahasa)
**Dokumentasi Respons**
* Respons sukses (200/201) dengan skema dan contoh
* Semua respons kesalahan (400, 401, 403, 404, 409, 429, 500) dengan contoh
* Informasi pembatasan tingkat permintaan (Rate limiting)
* Header respons (jika relevan)
**Tambahan**
* Endpoint atau panduan terkait
* Riwayat versi jika berlaku
* Peringatan deprecation (jika tidak digunakan lagi)
## Instruksi
Saat dipanggil:
1. **Pindai file endpoint** di /docs/api/
2. **Periksa setiap endpoint** terhadap kriteria peninjauan
3. **Catat item yang hilang** dengan referensi file/baris spesifik
4. **Identifikasi masalah kejelasan** (deskripsi yang tidak jelas, istilah yang tidak terdefinisi)
5. **Tandai masalah konsistensi** (pergeseran terminologi, perbedaan format)
6. **Hasilkan daftar periksa** perbaikan yang diperlukan
7. **Tawarkan untuk menerapkan perbaikan** dengan contoh
Format laporan:
ENDPOINT: POST /api/users File: docs/api/users.md Status: 65% Lengkap
Hilang:
- [ ] Dokumentasi respons kesalahan (400, 401, 409)
- [ ] Informasi pembatasan tingkat permintaan (Rate limiting)
- [ ] Definisi skema body permintaan
Masalah:
- Baris 45: "objek pengguna" tidak terdefinisi - tambahkan tautan ke skema
- Baris 60: Contoh usang - format respons berubah
Perbaikan tersedia: Ya (minta untuk menerapkan)
Langkah 3: Daftarkan Skill
Tambahkan ke .claude/skills.md:
# Dokumentasi Skills yang Tersedia
## Dokumentasi API
### /api-docs-review
Audit dokumentasi API untuk kelengkapan terhadap kriteria standar.
- **Versi**: 1.0.0
- **Penggunaan**: `/api-docs-review [--file PATH] [--endpoint NAME]`
- **Kapan digunakan**: Sebelum rilis API, setelah perubahan kode
- **Waktu**: 5-10 menit untuk API ukuran sedang
Langkah 4: Uji Skill
# Di Claude Code
/api-docs-review
Claude sekarang akan mengaudit dokumentasi API Anda secara sistematis.
Pola Dokumentasi Tingkat Lanjut
Pola 1: Pelacakan Dokumentasi Berversi
Skills dapat melacak kualitas dokumentasi di berbagai versi:
## Riwayat Versi
### v2.0.0 [2026-01-22]
Kelengkapan: 95% ✅
- Semua endpoint didokumentasikan
- Respons kesalahan lengkap
- Contoh diperbarui
- Endpoint /v1 yang tidak digunakan lagi ditandai
### v1.0.0 [2025-12-01]
Kelengkapan: 70%
- Dokumentasi kesalahan hilang
- Contoh usang
- Tidak ada peringatan deprecation
Claude mendeteksi peningkatan dari waktu ke waktu.
Pola 2: Validasi Spesifikasi API Terhadap Kode
Skills dapat memvalidasi spesifikasi OpenAPI agar sesuai dengan implementasi:
## Validasi Spesifikasi
Bandingkan /api/openapi.yaml dengan kode:
1. **Pindai implementasi** untuk semua rute
2. **Periksa spesifikasi OpenAPI** untuk setiap rute
3. **Tandai endpoint yang hilang**
4. **Verifikasi parameter** cocok dengan implementasi
5. **Perbarui contoh** agar sesuai dengan skema saat ini
Hasil: Spesifikasi 100% sinkron dengan kode
Otomatisasi dengan CI/CD
Pipeline Validasi Dokumentasi
Siapkan pemeriksaan otomatis pada setiap pembaruan dokumentasi:
# .github/workflows/docs-check.yml
name: Pemeriksaan Dokumentasi
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: Instal Apidog CLI
run: npm install -g apidog-cli
- name: Validasi Spesifikasi OpenAPI
run: |
apidog lint api/openapi.yaml
apidog check-completeness api/openapi.yaml --min-score 85
- name: Periksa tautan yang rusak
run: |
npm install -g markdown-link-check
find docs -name "*.md" -exec markdown-link-check {} \;
- name: Verifikasi contoh valid
run: |
# Uji contoh curl berfungsi
bash scripts/test-curl-examples.sh
- name: Komentar pada 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: '❌ Validasi dokumentasi gagal. Tinjau log alur kerja.'
})
Skenario Dunia Nyata: Kelengkapan Dokumentasi API
Mari kita audit set dokumentasi API realistis untuk kelengkapan dan menerapkan peningkatan.
Skenario
Anda memiliki dokumentasi REST API yang berusia 6 bulan. Sebagian lengkap tetapi tidak memiliki dokumentasi kesalahan, tidak jelas di beberapa tempat, dan memiliki contoh yang usang.
Audit
Prompt untuk Claude: "Audit dokumentasi di /docs/api/. Untuk setiap endpoint, periksa: deskripsi, parameter permintaan, contoh respons, dan semua respons kesalahan. Prioritaskan perbaikan berdasarkan dampak."
HASIL AUDIT
=============
KRITIS (Dokumen kesalahan hilang):
├── POST /api/users - Respons kesalahan 400, 401, 409 hilang
├── POST /api/auth/login - Respons 429 (rate limit) hilang
└── DELETE /api/resources/{id} - Respons 403 (terlarang) hilang
TINGGI (Masalah kejelasan):
├── users.md:45 - "objek pengguna" tidak terdefinisi
├── auth.md:60 - "Atur masa berlaku ke nilai yang sesuai" - terlalu tidak jelas
└── resources.md:30 - Deskripsi format kursor paginasi hilang
SEDANG (Contoh usang):
├── products.md:120 - Contoh cURL mengembalikan format lama
├── orders.md:80 - Contoh SDK Python menggunakan parameter usang
└── webhooks.md:60 - Contoh Node.js tidak memiliki penanganan kesalahan
KONSISTENSI:
├── "API key" vs "access token" - 5 instansi tidak konsisten
├── Format body permintaan - 3 gaya berbeda di seluruh endpoint
└── Skema respons kesalahan - 2 variasi alih-alih 1
Perbaikan prioritas: total 15
Estimasi usaha: 2-3 jam manual, 15 menit dengan Claude Code
Peningkatan
Menerapkan perbaikan secara sistematis:
Sebelum - POST /api/users (Tidak Lengkap):
## Buat Pengguna
POST /api/users
Membuat pengguna baru.
**Parameter:**
- name: Nama pengguna
- email: Email pengguna
**Respons:**
```json
{
"id": "usr_123",
"name": "Alice",
"email": "alice@example.com"
}
**Setelah - POST /api/users (Lengkap):**
```markdown
## Buat Pengguna
`POST /api/users`
Membuat akun pengguna baru dengan detail yang diberikan. Email harus unik.
### Autentikasi
Membutuhkan kunci API di header `Authorization`: `Bearer YOUR_API_KEY`
### Parameter Permintaan
| Parameter | Tipe | Wajib | Deskripsi |
|-----------|------|----------|-------------|
| `name` | string | Ya | Nama lengkap (2-100 karakter) |
| `email` | string | Ya | Email valid (harus unik) |
| `role` | string | Tidak | Peran: `admin`, `developer`, `viewer`. Default: `viewer` |
### Contoh Permintaan
```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"
}'
Respons (201 Dibuat)
{
"id": "usr_abc123",
"name": "Alice Smith",
"email": "alice@example.com",
"role": "developer",
"created_at": "2026-01-22T10:30:00Z"
}
Respons Kesalahan
400 Bad Request - Input tidak valid
{
"error": "validation_error",
"message": "Format email tidak valid",
"field": "email",
"request_id": "req_xyz789"
}
401 Unauthorized - Kunci API hilang/tidak valid
{
"error": "unauthorized",
"message": "Kunci API tidak valid",
"request_id": "req_xyz789"
}
409 Conflict - Email sudah ada
{
"error": "conflict",
"message": "Pengguna dengan email ini sudah ada",
"request_id": "req_xyz789"
}
429 Too Many Requests - Batas permintaan terlampaui
{
"error": "rate_limited",
"message": "Terlalu banyak permintaan. Coba lagi dalam 60 detik.",
"retry_after": 60,
"request_id": "req_xyz789"
}
Pembatasan Tingkat Permintaan (Rate Limiting)
100 permintaan per menit per kunci API. Lihat Batas Permintaan.
**Peningkatan yang diterapkan:**
- Menambahkan persyaratan autentikasi
- Mendokumentasikan semua parameter dengan batasan
- Respons sukses lengkap + semua respons kesalahan
- Contoh cURL siap produksi
- Informasi pembatasan tingkat permintaan
- Pemformatan yang konsisten
Mengintegrasikan Claude dengan Apidog untuk Dokumentasi API yang Unggul
💡 Tips Pro: Manfaatkan Claude untuk tinjauan mendalam terhadap dokumen naratif, sementara Apidog memastikan spesifikasi API Anda kuat dan mengisi celah secara otomatis dengan contoh-contoh praktis.
Prompt yang Disarankan untuk Claude:"Periksa /docs/api/ untuk kejelasan dan keterlibatan secara keseluruhan. Selanjutnya, periksa ulang kelengkapan file /api/openapi.yaml menggunakan Apidog. Sorot setiap inkonsistensi atau elemen yang hilang, sehingga saya dapat mengatasinya langsung di Apidog sebelum melanjutkan."
Bash
# Langkah 1: Tinjauan Prosa Awal melalui Claude
> /docs-completeness # Menghasilkan saran untuk bahasa dan struktur yang lebih jelas
# Langkah 2: Validasi Spesifikasi API di Apidog
apidog check-completeness api/openapi.yaml # Menandai masalah seperti skema tidak lengkap atau respons hilang
# Langkah 3: Hasilkan Konten Secara Otomatis dengan AI Apidog
# (Melalui UI Apidog: Pengaturan → AI → Hasilkan deskripsi, contoh, dan ringkasan secara otomatis)
# Langkah 4: Pemeriksaan Harmoni Akhir dengan Claude
> /consistency-check # Memastikan dokumen dan spesifikasi selaras sempurnaIni menciptakan alur kerja di mana Apidog menangani validasi spesifikasi terstruktur dan Claude Code menangani kualitas prosa.
Praktik Terbaik untuk Peninjauan Dokumentasi
Kenali Audiens Anda
Sesuaikan kedalaman dokumentasi dengan pembaca:
| Audiens | Gaya | Contoh |
|---|---|---|
| Pengembang | Contoh kode dalam berbagai bahasa | cURL, Python, JS |
| DevOps | Langkah-langkah penerapan, konfigurasi | Contoh Kubernetes YAML |
| Tim Produk | Alur kerja tingkat tinggi, diagram | Alur fitur dengan tangkapan layar |
| Dukungan | Pemecahan masalah, masalah umum | "Error 429 berarti..." |
Prioritaskan Kejelasan
Tulis dalam kalimat aktif, strukturkan untuk pemindaian:
❌ Sebelum: "Permintaan diajukan melalui POST. Respons akan berisi pengguna."
✅ Setelah: "Ajukan permintaan POST untuk membuat pengguna. API mengembalikan pengguna baru."
Selalu Sertakan Contoh
Konsep abstrak membutuhkan penjangkaran. Setiap endpoint API membutuhkan:
# ✅ Siap copy-paste
curl -X GET https://api.example.com/v1/users/usr_123 \
-H "Authorization: Bearer YOUR_API_KEY"
Kesalahan Umum
| Kesalahan | Solusi |
|---|---|
| Terlalu banyak jargon | Definisikan istilah pada penggunaan pertama |
| Contoh usang | Uji di CI/CD |
| Dokumen kesalahan hilang | Dokumentasikan semua kode kesalahan |
| Pemformatan tidak konsisten | Gunakan templat |
| Tautan rusak | Periksa di CI/CD |
Kesimpulan
Claude Code Skills mengubah peninjauan dokumentasi teknis dari proses manual yang membosankan menjadi alur kerja cerdas dan otomatis. Anda menjelaskan apa yang perlu ditinjau, dan Claude mengaudit seluruh repositori dokumentasi Anda, mengidentifikasi celah dan inkonsistensi, serta menerapkan perbaikan, semuanya sambil menjaga standar kualitas.
Dikombinasikan dengan Apidog untuk validasi spesifikasi API, Anda mencapai cakupan dokumentasi yang komprehensif.