Validasi Spec Kit Golang: Audit Otomatis Implementasi vs Spesifikasi
Panduan lengkap menggunakan specify audit untuk validasi otomatis implementasi Golang terhadap spesifikasi. Continuous validation, audit modes, custom rules, dan CI integration.
Validasi Implementasi terhadap Spesifikasi: Audit Otomatis
Validasi implementasi Spec Kit Golang dengan audit otomatis adalah kunci untuk memastikan kode benar-benar memenuhi spesifikasi, bukan sekadar “terlihat jadi”. Di artikel 15 kita sudah melihat specify audit sebagai alat debugging. Tapi audit paling powerful ketika berjalan sebagai continuous validation — bagian dari workflow reguler, bukan hanya dipanggil saat ada masalah.
Di artikel ini kita bahas audit secara mendalam: cara kerjanya, semua mode yang tersedia, custom rules, dan bagaimana membangun quality gate yang reliable.
18.1 Philosophy: Spec sebagai Executable Test
Untuk memahami kenapa audit begitu penting, bandingkan dengan TDD. Di TDD, test adalah spesifikasi yang executable; di SDD, spec.md + specify audit adalah padanannya di level yang lebih tinggi. Diagram berikut menyandingkan kedua flow tersebut.
1TDD Flow:
2 Write failing test → Implement → Make test pass → Refactor
3
4SDD + Audit Flow:
5 Write spec → Implement → Run audit → Fix deviation → Re-auditPerbedaan kuncinya: TDD memverifikasi kode di level unit, sedangkan SDD audit memverifikasi kode terhadap business requirement. Keduanya dibutuhkan dan saling melengkapi, bukan saling menggantikan.
18.2 Cara Kerja Audit Secara Internal
Sebelum mengandalkan skornya, penting memahami apa yang terjadi di balik specify audit. Pipeline berikut memecah proses audit menjadi lima langkah, dari parsing spec hingga generate report.
1specify audit pipeline:
2
3Step 1: Parse spec.md
4 → Extract AC list (AC1-AC16)
5 → Extract EC list (EC1-EC3)
6 → Extract NFR
7
8Step 2: Build context
9 → Read CLAUDE.md + constitution.md
10 → Read existing code structure
11
12Step 3: Per-AC analysis
13 For each AC:
14 a. AI reasoning: layer mana yang handle AC ini?
15 b. Static code scan: grep + AST analysis
16 c. Test coverage check: ada test untuk AC ini?
17 d. Response format check: HTTP status + error code match?
18 e. Result: PASS | FAIL | WARNING | PARTIAL | ACKNOWLEDGED
19
20Step 4: Architecture check
21 → Cross-layer import detection
22 → Error propagation pattern
23 → Context propagation
24
25Step 5: Generate report + scoreKombinasi AI reasoning dan static analysis inilah yang membuat audit bisa menilai bukan hanya “apakah kode ada” tapi “apakah kode benar-benar memenuhi maksud tiap AC”.
18.3 Semua Audit Modes
specify audit punya banyak mode untuk konteks pemakaian berbeda — dari cek cepat tanpa LLM hingga output JSON untuk scripting. Daftar berikut merangkum sepuluh mode yang paling sering dipakai.
1# Mode 1: Basic (AC only, ~3 menit)
2specify audit --feature product-review
3
4# Mode 2: Comprehensive (AC + EC + NFR + Architecture, ~6 menit)
5specify audit --feature product-review --comprehensive
6
7# Mode 3: Fast (static analysis only, tanpa LLM, ~30 detik)
8specify audit --feature product-review --fast
9
10# Mode 4: Diff audit (hanya perubahan sejak commit tertentu)
11specify audit --feature product-review --since-commit abc123
12
13# Mode 5: Watch mode (re-run saat file berubah)
14specify audit --feature product-review --watch
15
16# Mode 6: All features
17specify audit --all
18
19# Mode 7: Score only (untuk CI scripting)
20specify audit --feature product-review --score --format number
21
22# Mode 8: JSON output
23specify audit --feature product-review --output json > audit.json
24
25# Mode 9: GitHub-native summary
26specify audit --feature product-review --output github-summary
27
28# Mode 10: Executive summary
29specify audit --feature product-review --output executive-summaryPilih mode sesuai konteks: --fast untuk pre-commit, --comprehensive untuk PR, dan --score --format number ketika kamu butuh angka mentah untuk logika CI.
18.4 Audit Report Komprehensif
Agar terasa konkret, mari lihat seperti apa output audit comprehensive untuk fitur nyata. Report berikut memperlihatkan status per-AC, skor per kategori, dan daftar priority fix.
1specify audit --feature product-review --comprehensive
2
3# Output ringkasan:
4# ========================================
5# Spec Audit Report: product-review
6# ========================================
7#
8# ACCEPTANCE CRITERIA (16 total)
9# AC1 ✅ POST endpoint — router.go:45
10# AC2 ✅ Purchase verify — create_review.go:67
11# AC3 ✅ Status PUBLISHED — entity.go:12
12# AC4 ✅ Atomic TX — review_repository.go:234
13# AC5 ✅ Response 201 — handler.go:98
14# AC6 ✅ GET + pagination — handler.go:134
15# AC7 ✅ Avg rating in response — list_reviews.go:89
16# AC8 ✅ Admin-only DELETE — delete_review.go:45
17# AC9 ✅ Soft delete — review_repository.go:456
18# AC10 ✅ Rating recalculate — review_repository.go:478
19# AC11 ✅ Rating 1-5 validation — entity.go:67
20# AC12 ❌ Content length validation — MISSING
21# entity.go only checks empty, not length
22# Action: Add len(r.Content) <= 1000 to validate()
23# AC13 ✅ PURCHASE_REQUIRED — handler.go:145 (exact match)
24# AC14 ✅ ALREADY_REVIEWED — handler.go:157
25# AC15 ✅ 404 NOT_FOUND — handler.go:167
26# AC16 ✅ 403 FORBIDDEN — handler.go:177
27#
28# AC Score: 15/16 (93.8%)
29#
30# EDGE CASES: 2/3 + 1 acknowledged (100% effective)
31# ARCHITECTURE: 3/4 (context timeout missing in 3 repo methods)
32# NFR: 0/1 (missing pagination index)
33#
34# OVERALL: 83.2/100 — WARNING (threshold: 85)
35#
36# Priority fixes:
37# 🔴 AC12: content length (10 min)
38# 🟡 NFR: pagination index (15 min)
39# 🟡 Arch: context timeout (30 min, 3 locations)Yang membuat report ini actionable bukan sekadar skornya, tapi pointer file:line untuk tiap deviation plus estimasi waktu fix — audit langsung memberitahu apa yang harus dikerjakan dan seberapa besar effort-nya.
18.5 Custom Audit Rules
Selain aturan bawaan, kamu bisa menambahkan rules spesifik proyek yang tidak mungkin ditangkap general rules. Konfigurasi berikut mendefinisikan empat custom rule — dari larangan float64 untuk uang hingga konvensi penamaan test.
1# .speckit-config.yaml
2
3audit:
4 custom_rules:
5 - name: "error-code-uppercase"
6 description: "All error codes must be UPPERCASE_SNAKE_CASE"
7 severity: "critical"
8 check_type: "grep"
9 pattern: '"error":\s*"[a-z]'
10 target: "internal/delivery/http/handler/"
11 fail_message: "Found lowercase error code in handler"
12
13 - name: "no-float64-money"
14 description: "No float64 for monetary values"
15 severity: "critical"
16 check_type: "grep"
17 pattern: 'float64.*[Pp]rice|float64.*[Aa]mount|float64.*[Cc]ents'
18 target: "internal/"
19
20 - name: "context-timeout-required"
21 description: "Repository methods must use context timeout"
22 severity: "warning"
23 check_type: "script"
24 script: |
25 find internal/repository -name "*.go" -not -name "*_test.go" | \
26 xargs grep -L "context.WithTimeout\|context.WithDeadline" || true
27 fail_on_output: true
28
29 - name: "test-naming-convention"
30 description: "Test functions must follow: Test{Subject}_{Scenario}"
31 severity: "info"
32 check_type: "regex"
33 pattern: "func Test[A-Z][a-zA-Z]+_[A-Z][a-zA-Z]+"
34 target: "internal/**/*_test.go"
35 check_mode: "all_match"Custom rules inilah yang menegakkan konvensi khas tim — misalnya larangan float64 untuk nilai uang — yang tidak akan pernah ditangkap oleh aturan generik mana pun.
18.6 Audit Scoring Configuration
Skor audit bisa disesuaikan dengan prioritas tim lewat pembobotan tiap kategori. Konfigurasi berikut mengatur bobot AC/EC/architecture/NFR, threshold pass, dan cara mendokumentasikan exception yang disengaja.
1# .speckit-config.yaml
2
3audit:
4 scoring:
5 ac_weight: 50
6 ec_weight: 25
7 architecture_weight: 15
8 nfr_weight: 10
9
10 pass_threshold: 90
11 warning_threshold: 85
12 fail_threshold: 85
13
14 # Documented exceptions
15 acknowledged_ecs:
16 - ec_id: "EC3"
17 reason: "Product cascade: reviews orphaned saat product deleted (Out of Scope per spec)"
18 acknowledged_by: "@budi"
19 acknowledged_date: "2025-07-02"Bagian acknowledged_ecs penting: ia memberi jalur formal untuk mendokumentasikan deviasi yang memang disengaja — sebuah keputusan tercatat, bukan bypass diam-diam yang bisa menggigit di kemudian hari.
18.7 Audit dalam Pre-commit Hook
Menangkap masalah sedini mungkin jauh lebih murah daripada di CI. Hook pre-push berikut menjalankan audit fast-mode otomatis setiap kali kamu push dari feature branch.
1# .git/hooks/pre-push
2#!/bin/bash
3BRANCH=$(git rev-parse --abbrev-ref HEAD)
4
5if [[ "$BRANCH" == feature/* ]]; then
6 FEATURE=$(echo "$BRANCH" | sed 's/feature\/[A-Z0-9]*-//')
7
8 if [ -d ".specify/features/$FEATURE" ]; then
9 echo "🔍 Fast spec audit for $FEATURE..."
10 specify audit --feature "$FEATURE" --fast
11
12 if [ $? -ne 0 ]; then
13 echo "❌ Spec audit failed. Run: specify audit --feature $FEATURE"
14 exit 1
15 fi
16 echo "✅ Fast audit passed"
17 fi
18fiAgar tidak perlu memasang hook manual, Spec Kit menyediakan installer yang menempatkan hook ini otomatis lewat satu perintah berikut.
1# Install hook otomatis
2specify hooks install --hook pre-pushDengan hook fast-mode ini, deviasi obvious tertangkap dalam ~30 detik sebelum sampai ke remote — nyaris gratis karena berjalan tanpa LLM.
18.8 Audit-Driven Development
Audit bisa dijadikan driver implementasi, persis seperti TDD memakai test yang gagal. Alur berikut menunjukkan siklus red-to-green di mana skor audit naik seiring tiap task selesai.
1# 1. Tulis spec
2specify feature
3
4# 2. Audit segera (sebelum implement) → semua fail
5specify audit --feature product-review
6# Output: 0/16 ACs (0%)
7
8# 3. Implement task pertama
9specify implement --task 01
10
11# 4. Re-audit → progress terlihat
12specify audit --feature product-review
13# Output: 2/16 ACs (12.5%)
14
15# 5. Lanjut sampai 100%
16# Seperti TDD: red → green → refactorMemakai audit sebagai kompas membuat progress jadi terukur secara objektif — kamu tahu persis berapa persen requirement yang sudah terpenuhi di setiap langkah.
18.9 Phased Release Support
Tidak semua AC harus rilis sekaligus; audit mendukung rilis bertahap. Konfigurasi berikut mendefinisikan dua fase dengan subset AC dan threshold berbeda.
1# .speckit-config.yaml
2audit:
3 phases:
4 phase_1:
5 included_acs: ["AC1", "AC2", "AC3", "AC5", "AC11", "AC13"]
6 excluded_acs: ["AC4", "AC6", "AC7", "AC8", "AC9", "AC10", "AC12", "AC14"]
7 threshold: 95
8
9 phase_2:
10 included_acs: all
11 threshold: 90Dengan konfigurasi fase ini, kamu bisa mengaudit hanya subset yang relevan untuk rilis pertama seperti contoh berikut.
1# Audit phase 1 saja
2specify audit --feature product-review --phase 1
3# Output: 6/6 ACs (100%) PASS — Phase 1 ready for release
4# Note: 10 ACs deferred to Phase 2Pendekatan phased ini memungkinkan MVP rilis lebih cepat tanpa kehilangan jejak AC mana yang sengaja ditunda ke fase berikutnya.
18.10 Audit Evidence Trail
Menyimpan bukti tiap audit berguna untuk melacak perbaikan dari waktu ke waktu. Perintah berikut menyimpan evidence lengkap dan menampilkan history skor sebuah fitur.
1# Save audit dengan full evidence
2specify audit --feature product-review --save-evidence
3
4# Output di:
5# .specify/audit/product-review/2025-07-02-14-30.json
6# .specify/audit/product-review/2025-07-02-14-30.md
7# .specify/audit/product-review/latest.json
8
9# Lihat history
10specify audit --history --feature product-review
11# 2025-07-02 14:30 Score: 83.2 WARNING (pre-fix)
12# 2025-07-02 16:00 Score: 96.4 PASS (post-fix)
13# 2025-07-03 09:00 Score: 97.1 PASS (CI verify)Evidence trail ini menjadikan perbaikan kualitas dapat dibuktikan: kamu bisa menunjukkan skor naik dari 83.2 ke 97.1 lengkap dengan timestamp dan konteksnya.
18.11 Scheduled Weekly Audit
Selain per-PR, audit terjadwal mingguan menangkap degradasi kualitas yang menumpuk perlahan. Workflow berikut menjalankan audit semua fitur tiap Senin dan membuat issue otomatis jika skor menurun.
1# .github/workflows/weekly-audit.yml
2on:
3 schedule:
4 - cron: '0 8 * * MON'
5
6jobs:
7 weekly-audit:
8 steps:
9 - run: specify audit --all --comprehensive --output markdown > weekly-report.md
10
11 - name: Check for degradation vs last week
12 run: |
13 python3 detect_degradation.py weekly-scores.json prev-scores.json
14
15 - name: Create issue if degraded
16 if: failure()
17 run: |
18 gh issue create \
19 --title "⚠️ Weekly Audit: Score Degradation" \
20 --body "$(head -100 weekly-report.md)" \
21 --label "spec-debt,priority-high"Audit terjadwal ini berfungsi sebagai jaring pengaman jangka panjang — spec debt yang tumbuh diam-diam akan muncul sebagai issue sebelum menumpuk menjadi masalah besar.
18.12 Audit untuk Legacy Code
Audit juga bisa diterapkan ke kode lama yang belum punya spec, lewat reverse engineering. Perintah berikut membangun spec dari kode existing lalu mengauditnya untuk menghasilkan daftar technical debt.
1# Buat spec dari existing code (reverse engineering)
2specify reverse-spec --from-code internal/usecase/order/cancel_order.go
3
4# Audit menghasilkan technical debt list
5specify audit --feature cancel-order
6# Score: 72/100 — menunjukkan technical debt yang perlu di-addressSkor 72/100 di sini bukan kegagalan, melainkan peta jalan: ia mengubah “kode lama yang menakutkan” menjadi daftar perbaikan konkret yang bisa diprioritaskan.
18.13 Audit Report sebagai PR Artifact
Menautkan hasil audit langsung ke PR membuat reviewer melihat skor tanpa perlu menjalankan apa pun. Snippet berikut meng-upload report sebagai artifact dan memposting skor sebagai komentar PR.
1# Upload audit report ke GitHub Actions
2- name: Upload audit report
3 uses: actions/upload-artifact@v4
4 with:
5 name: spec-audit-${{ github.run_number }}
6 path: .specify/audit/*/latest.md
7
8# Comment ke PR
9- name: Comment audit score
10 uses: actions/github-script@v7
11 with:
12 script: |
13 const score = '${{ steps.audit.outputs.score }}';
14 const status = parseInt(score) >= 90 ? '✅' : '⚠️';
15 github.rest.issues.createComment({
16 issue_number: context.issue.number,
17 owner: context.repo.owner,
18 repo: context.repo.repo,
19 body: `## Spec Audit\n\n${status} Score: **${score}/100**`
20 });Dengan skor tampil langsung di PR, kualitas spec compliance menjadi bagian visible dari review — bukan sesuatu yang harus dikejar reviewer secara manual.
18.14 ROI dari Continuous Audit
Pertanyaan wajar dari continuous audit adalah: apakah sepadan biayanya? Output metrics berikut membandingkan deviasi yang tertangkap audit dengan yang lolos ke production beserta hitungan biayanya.
1specify metrics --audit-effectiveness --since "2025-01-01"
2
3# Output:
4# Audit Effectiveness — Jan-Jul 2025
5#
6# Deviations caught by audit: 47
7# Deviations reached production: 3
8#
9# Cost of post-deploy fixes: 12 hours × $80 = $960
10# Cost of audit (tokens + time): ~$1,245
11# Net: -$285 (but: reduced regressions, faster review, better docs)
12#
13# Token ROI on post-deploy saves: 21.2xAngka net -$285 tampak merah di atas kertas, tapi nilai sebenarnya ada di 44 deviasi yang tak pernah mencapai production — regresi yang dicegah, review yang lebih cepat, dan dokumentasi yang selalu akurat.
18.15 Audit dalam Definition of Done
Agar audit benar-benar mengikat, ia perlu masuk ke Definition of Done tim. Checklist berikut menambahkan ambang skor audit sebagai syarat sebuah fitur dianggap selesai.
1## Team Definition of Done
2
3Feature DONE ketika:
4- [ ] All tasks checked in tasks.md
5- [ ] go test -race passes
6- [ ] Coverage ≥ 85%
7- [ ] golangci-lint — 0 issues
8- [ ] **specify audit --score ≥ 90** ← added
9- [ ] PR description includes audit score
10- [ ] CLAUDE.md updated if new patterns
11- [ ] Code review approvedMenaruh specify audit --score ≥ 90 di DoD mengubah audit dari “nice to have” menjadi gerbang yang setara dengan test dan lint — tidak ada fitur yang dianggap selesai tanpanya.
18.16 Prometheus Integration untuk Dashboarding
Untuk visibilitas jangka panjang, metrics audit bisa diekspor ke sistem monitoring. Perintah berikut menghasilkan output format Prometheus yang siap di-scrape dan divisualisasikan di Grafana.
1# Export audit metrics untuk Grafana
2specify audit --all --output prometheus > /tmp/spec_metrics.txt
3
4# Output:
5# spec_audit_score{feature="product-review"} 96.4
6# spec_audit_score{feature="cancel-order"} 97.1
7# spec_audit_score{feature="flash-sale"} 82.3
8# spec_ac_compliance{feature="product-review"} 1.0
9# spec_coverage_pct{feature="product-review"} 89.4Dengan metrics ini masuk ke Prometheus, skor spec compliance jadi bisa di-dashboard dan di-alert seperti metrik operasional lain — kualitas spec menjadi terukur di level organisasi.
18.17 Audit sebagai Onboarding Checkpoint
Audit ternyata juga alat onboarding yang efektif untuk developer baru. Checklist berikut menjadikan analisis hasil audit sebuah fitur sebagai assessment pemahaman codebase di minggu pertama.
1## Developer Onboarding: Week 1 Spec Assessment
2
3### Task
4Jalankan: specify audit --feature cancel-order --comprehensive
5
6### Expected Outcomes
7Kamu bisa:
8- [ ] Menjelaskan mengapa setiap AC pass/fail
9- [ ] Mengidentifikasi akar masalah deviation
10- [ ] Menyarankan fix yang tepat
11- [ ] Memahami architecture check results
12
13Ini membuktikan kamu memahami codebase, bukan hanya membaca kode.Latihan ini memaksa developer baru benar-benar menelusuri hubungan spec-ke-kode — cara belajar codebase yang jauh lebih dalam ketimbang sekadar membaca file satu per satu.
18.18 Audit Quality Gate: Full Configuration
Sebagai quality gate di CI, audit perlu menerjemahkan skor menjadi keputusan pass/warning/fail. Step berikut mengambil skor numerik lalu memutuskan apakah pipeline lanjut atau gagal.
1# .github/workflows/spec-audit.yml
2- name: Run spec audit
3 id: audit
4 env:
5 ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
6 run: |
7 SCORE=$(specify audit --feature $FEATURE --score --format number)
8 echo "score=$SCORE" >> $GITHUB_OUTPUT
9
10 # Warning: 85-89
11 if [ "$SCORE" -ge "85" ] && [ "$SCORE" -lt "90" ]; then
12 echo "⚠️ WARNING: Score $SCORE (below recommended 90)"
13 fi
14
15 # Fail: below 85
16 if [ "$SCORE" -lt "85" ]; then
17 echo "❌ FAIL: Score $SCORE < 85 minimum"
18 exit 1
19 fi
20
21 echo "✅ PASS: Score $SCORE/100"Logika tiga tingkat ini — pass, warning, fail — memberi ruang toleransi yang realistis: skor 85-89 lolos dengan peringatan, sementara di bawah 85 memblokir merge sepenuhnya.
18.19 Three-Layer Audit Strategy
Strategi audit paling efektif memakai tiga lapisan dengan biaya dan kedalaman berbeda:
Layer 1 — Pre-commit (30 detik, fast mode): menangkap masalah obvious sebelum push, tanpa LLM, gratis.
Layer 2 — CI per PR (5 menit, full mode): comprehensive AC + architecture + NFR check, LLM-powered, ~$0.05-0.10 per run.
Layer 3 — Weekly scheduled (15-30 menit, all features): mendeteksi spec debt yang terakumulasi dan menghasilkan issue otomatis jika terjadi degradasi.
Untuk menilai kelayakan biayanya, rincian estimasi berikut menunjukkan total pengeluaran bulanan ketiga lapisan.
1Cost breakdown (estimasi per bulan, 10 features, 4 sprints):
2Layer 1: Gratis (static analysis)
3Layer 2: ~$2-5 (CI, setiap PR)
4Layer 3: ~$1-2 (weekly, semua features)
5Total: ~$3-7/bulan
6
7Value: mencegah post-deploy debugging yang bisa cost 10-100x lebih mahalTotal $3-7 per bulan terasa sepele dibanding satu sesi debugging post-deploy — inilah kenapa arsitektur tiga lapis ini punya rasio biaya-manfaat yang sangat menguntungkan.
18.20 Ringkasan
specify audit sebagai continuous validation mengubah spec dari dokumentasi pasif menjadi test suite yang aktif — berjalan sepanjang lifecycle feature.
Tiga lapisan: pre-commit (fast, gratis), CI per PR (LLM-powered), dan weekly scheduled (comprehensive semua features).
Custom rules menegakkan konvensi khas proyek yang tidak bisa ditangkap oleh general rules.
Acknowledged exceptions adalah cara formal mendokumentasikan deviasi yang disengaja — bukan bypass.
ROI: 47 deviasi tertangkap pre-production vs 3 yang sampai ke production — token ROI 21x hanya dari penghematan post-deploy fix saja.
Di artikel berikutnya, kita bahas integrasi Spec Kit dengan GitHub Actions secara komprehensif — full CI pipeline dengan spec validation, audit, quality gate, dan PR automation.