devguard

devguard คือระบบควบคุมมาตรฐานการทำงานแบบต้องมีหลักฐานจริง (verified-dev) ผสานกับชุดเครื่องมือประหยัด Token ที่ล็อกเวอร์ชันเสถียรไว้ให้ ติดตั้งเพียงครั้งเดียวแล้วแชร์ทั้งกฎการทำงานและเครื่องมือทั้งหมดร่วมกันได้ทุก Agent: Claude Code, VS Code (Copilot), Google Antigravity, Cursor, OpenCode, Codex CLI และ Gemini CLI

การติดตั้ง (Installation)

ปิดโปรแกรม Claude Code, VS Code และ Antigravity ก่อนรันคำสั่ง (เพื่อไม่ให้โปรแกรมเขียนทับไฟล์ตั้งค่าตอนปิด) จากนั้นรันคำสั่งเดียวใน Terminal หรือ PowerShell:

curl -fsSL https://raw.githubusercontent.com/Burapa-J/devguard/main/bootstrap.sh | bash

irm https://raw.githubusercontent.com/Burapa-J/devguard/main/bootstrap.ps1 | iex

สคริปต์ bootstrap.sh / bootstrap.ps1 จะทำงานดังนี้โดยอัตโนมัติ:

1. ติดตั้งเครื่องมือพื้นฐานที่ยังขาดผ่าน Homebrew บน macOS, apt-get บน Linux หรือ winget บน Windows (git, jq, python3, node, xcbeautify บน macOS, ast-grep, shellcheck)
2. Clone โปรเจกต์ไว้ที่ ~/.local/share/agent-kit/src (หรืออัปเดตของเดิมหากเคยติดตั้งแล้ว)
3. รัน ./install.sh (ผ่าน Git Bash บน Windows) ด้วยค่าเริ่มต้นที่แนะนำ: ติดตั้งกฎหลัก, สกิล verified-dev, hook เตือนหลัง compact, เชื่อม codegraph + projectmem + rtk และเปิดการตั้งค่าโปรเจกต์อัตโนมัติใน ~/Developer
4. เพิ่ม ~/.local/bin เข้า PATH (ใน ~/.zshrc หรือ User PATH ของ Windows พร้อมไฟล์ .cmd shim สำหรับเรียกใช้จาก PowerShell และ CMD)

ตัวเลือกการติดตั้งเพิ่มเติม

./install.sh --dry-run                                        # ดูสิ่งที่จะเปลี่ยนโดยไม่แก้ไขไฟล์จริง
./install.sh --with=codegraph,projectmem,rtk,context-mode     # เปิดใช้งาน context-mode เพิ่มเติม
./install.sh --targets=claude,vscode,antigravity              # เลือกติดตั้งเฉพาะบาง Agent
./install.sh --auto-project=~/Developer,~/Work                # กำหนดโฟลเดอร์ที่ให้ตั้งค่าโปรเจกต์อัตโนมัติ

เริ่มต้นอย่างรวดเร็ว (Quickstart)

หลังติดตั้งเสร็จ ให้เปิด Terminal แท็บใหม่ แล้วตรวจสอบสถานะด้วยคำสั่ง:

devguard status        # ดูตารางสถานะการเชื่อมต่อของทุก Agent และเครื่องมือ
devguard doctor        # ตรวจสุขภาพการติดตั้งทั้ง 8 ข้อ
devguard stats         # ดูสถิติการประหยัด Token และอัตราการ Verify ผ่าน
devguard gate init     # ใน repo: สร้าง .devguard/checks และติดตั้งด่านตอน commit/push

1. วิธีทำงาน (verified-dev)

พัฒนาต่อยอดจากแนวคิดของ pstack (Lauren Tan), Karpathy Guidelines และ Ponytail ประกอบด้วยกฎหลักขนาดสั้น 9 บรรทัด (rules/core.md) และสกิลเชิงลึก (skills/verified-dev/SKILL.md):

• เลือก Playbook ตามประเภทงาน: แยกขั้นตอนชัดเจนสำหรับ Investigation, Bug fix, Feature, Refactor, Perf issue และ Prompt / LLM pipeline
• โหมดอ่านอย่างเดียวเมื่อถามคำถามหรือรีวิวแผน: เมื่อคุณถามคำถามหรือปรึกษาทางเลือก AI จะไม่แก้ไขไฟล์ใดๆ จนกว่าคุณจะสั่งให้ลงมือ
• ห้ามเดาจาก --help หรือชื่อไฟล์: ก่อนอธิบายการทำงานของระบบหรือเสนอแผนออกแบบ AI ต้องอ่านโค้ดจริงทั้งขาอ่าน, ขาเขียน, การจัดการ ID/State และกรณีชนกัน พร้อมอ้างอิง file:line เสมอ
• เช็คผู้เรียกใช้ทั้งหมด (Sibling-Caller Check): ตรวจสอบทุกจุดที่เรียกใช้ฟังก์ชันผ่าน codegraph_explore ก่อนแก้ เพื่อให้จุดที่เกี่ยวข้องไม่พังตาม
• ต้องมีหลักฐานจากการรันจริงเสมอ: การ build ผ่านไม่ใช่ข้อพิสูจน์ ทุกครั้งที่บอกว่า "เสร็จ" ต้องอ่านไฟล์ .verify/<name>.log และสรุปใบเสร็จตรวจสอบสั้นๆ 1 บรรทัด (คำสั่ง, exit code, ผลลัพธ์หลัก และลิงก์ไฟล์ log) โดยแปะ log เต็มเฉพาะเมื่อพัง
• ทุกข้อเท็จจริงต้องบอกที่มา: ลงท้ายด้วย (read file:line), (ran: คำสั่ง → exit N), (inferred) หรือ (unchecked) หาหลักฐานก่อนตอบ และถ้าคำตอบเปลี่ยนต้องบอกว่าเปลี่ยนเพราะหลักฐานใด
• Pre-mortem ก่อนทำฟีเจอร์: ตาราง "อะไรจะพัง / เกิดเมื่อไร / ออกแบบกันอย่างไร / test ที่พิสูจน์" แถวที่ไม่มี test ต้องรายงานเป็นความเสี่ยงที่เปิดอยู่
• พิสูจน์ว่า test ล้มได้: test ใหม่จะนับได้ก็ต่อเมื่อเคยล้มด้วยเหตุผลที่ถูกต้อง (ก่อนแก้ หรือเมื่อถอดการป้องกันออก)
• ด่าน "เสร็จ": ถ้า repo มี .devguard/checks ต้องผ่าน devguard check ก่อนบอกว่าเสร็จ และห้ามข้าม hook ด้วย --no-verify

2. เครื่องมือที่ติดตั้งและดูแลให้ (Components & Companion Tools)

ติดตั้งตรงจากต้นทาง (Upstream) ด้วยเวอร์ชันที่ล็อกไว้ชัดเจน และไม่ใช้ local prompt proxy ที่ทำให้การเชื่อมต่อสะดุด

Agents ที่รองรับและตำแหน่งไฟล์

คำสั่ง CLI ทั้งหมด

การเก็บหลักฐานด้วย agent-verify

เพื่อไม่ให้ rtk ตัดทอนบรรทัดสำคัญของการทดสอบ คำสั่งตรวจสอบจะรันผ่าน agent-verify ซึ่งบันทึกผลลัพธ์เต็มลงไฟล์ .verify/<name>.log พร้อมชี้เลขบรรทัดที่เกิด error (errors_at=L...):

agent-verify unit-tests -- swift test
# ผลลัพธ์: agent-verify[unit-tests] exit=0 lines=42 log=.verify/unit-tests.log

agent-verify build-check -- xcodebuild test -scheme MyApp -destination 'platform=macOS'
# ผลลัพธ์: agent-verify[build-check] exit=65 lines=184 errors_at=L92,L141 log=.verify/build-check.log

ด่าน "เสร็จ" (.devguard/checks)

กฎเป็นแค่การขอให้ agent ตรวจงาน แต่ด่านนี้ตรวจให้จริงไม่ว่า model ไหนเขียนโค้ด แต่ละ repo เขียนคำสั่งตรวจจริงไว้ในไฟล์ .devguard/checks (commit เข้า repo) บรรทัดละหนึ่ง check:

commit build:   swift build                                    # ทุก commit: ต้องเร็ว
push   test:    swift test                                     # ก่อน push: suite เต็ม
commit secrets: gitleaks git --staged --redact --no-banner .   # เลือกใส่: กัน secret หลุดเข้า commit

devguard gate init สร้างไฟล์ตัวอย่างและติดตั้ง hook pre-commit / pre-push ส่วน devguard check ใช้รันเองได้ทุกเมื่อ ทุก check รันผ่าน agent-verify ถ้าล้มจะแสดงบรรทัดเดียว พร้อม log เต็มที่ .verify/gate-<name>.log

• ไม่ทับ hook ที่ไม่ได้เขียนเอง (จะบอกบรรทัดที่ต้องเพิ่มให้แทน) และใช้กับ worktree กับ core.hooksPath ได้
• ถ้าย้าย kit ไปที่อื่น จะปล่อย commit ผ่านพร้อมคำเตือน เพื่อไม่ให้ทุก repo ถูกบล็อก
• เตือนเมื่อ commit แก้ไฟล์ .devguard/checks และถ้าไฟล์เขียนผิดรูปแบบจะล้มพร้อมบอกเลขบรรทัด
• รัน check ด้วย SIGPIPE ค่าปกติและ Python แบบ isolated ผลจึงเหมือนรันใน terminal
• ข้อจำกัด: ตรวจ working tree ทั้งหมด ไม่ใช่เฉพาะส่วนที่ stage และ git commit --no-verify ยังข้ามได้ (กฎหลักห้ามไว้)

รีวิวข้ามค่าย (devguard review)

model แต่ละค่ายจับปัญหาได้ต่างกัน devguard review ส่งงาน (งานที่ยังไม่ commit รวมไฟล์ใหม่, commit ล่าสุด หรือทั้งช่วงด้วย --base REF) ให้ model อีกค่ายรีวิวแบบอ่านอย่างเดียวตาม rubric: บั๊ก, จุดที่อาจพัง, test ที่ผ่านแม้ไม่มีการแก้ และคำกล่าวอ้างที่โค้ดไม่รองรับ แสดงผลบรรทัดเดียว (verdict, จำนวนข้อ, path ของรายงาน) และเก็บรายงานไว้ที่ .verify/review-<เวลา>-<ผู้รีวิว>-<pid>.md

devguard review --with agy        # Claude เขียน: ให้ Gemini (ผ่าน Antigravity) รีวิว
devguard review --with claude     # Gemini เขียน: ให้ Claude รีวิว
devguard review --base main       # รีวิวทั้ง branch

เลือกค่ายที่ไม่ได้เขียนโค้ดนั้น Gemini CLI ปฏิเสธบัญชีส่วนตัวแล้ว ฝั่ง Gemini จึงใช้ agy แทน CLI ของผู้รีวิวต้อง login ใน terminal หนึ่งครั้ง ถ้ายังไม่ได้ login จะมีคำแนะนำบอก ผลรีวิวเป็นแค่ข้อสงสัย ต้องเปิดโค้ดยืนยันทีละข้อ

วัดผล agent (devguard eval)

การแก้กฎจะยังเป็นแค่สมมติฐานจนกว่าจะวัดผล ชุดคำถามเป็น JSON บรรทัดละข้อ มี prompt, regex expect, regex reject (ไม่บังคับ) และ pushback (ไม่บังคับ) สำหรับถามกดดันต่อในบทสนทนาเดิม:

devguard eval run .devguard/evals/kit.jsonl --with agy --reps 3 --label before
# ...แก้กฎ...
devguard eval run .devguard/evals/kit.jsonl --with agy --reps 3 --label after
devguard eval compare .verify/eval-before-*.json .verify/eval-after-*.json

รายงานผลรายข้อ: คำตอบแรกถูกหรือไม่, จำนวน tag ที่มาต่อคำตอบ และกลับคำบ่อยแค่ไหนเมื่อถูกกดดัน

หลักฐาน: รีวิวข้ามค่ายช่วยได้จริงไหม

นำ 7 commit ของ kit นี้มาสร้างเป็น repo แยก แล้วให้ Claude และ Gemini รีวิวแบบไม่เห็นคำตอบ เทียบกับบั๊กที่รู้แน่ 11 ข้อ: แต่ละค่ายจับได้ 8/11 และใช้สองค่ายรวมกันจับได้ 10/11 โดยแต่ละค่ายเจอบั๊กที่อีกค่ายพลาด commit ที่คิดว่าไม่มีบั๊กก็ถูกทั้งสองค่ายชี้ปัญหา และตรวจแล้วเป็นบั๊กจริง ส่วนเกณฑ์อัตโนมัติจาก diff สั่งให้รีวิวทุก commit ที่มีโค้ด จึงไม่ได้สร้าง ข้อสรุป: ให้ agent รันเฉพาะ devguard check กับทุกงานเป็นหลัก ส่วน devguard review ให้รันเฉพาะเมื่อผู้ใช้สั่งเท่านั้น (และแค่แนะนำท้ายงานเมื่อแก้จุดเสี่ยงสูง เช่น ข้อมูลถาวร, sync, concurrency หรือ security) ข้อจำกัด: รันครั้งเดียวต่อคู่ และบั๊ก 11 ข้อมาจากผู้เขียนคนเดียว จึงบอกได้แค่แนวโน้ม ไม่ใช่ตัวเลขที่แม่นยำ รายละเอียด: docs/experiments/2026-10-30-cross-model-review.md

การวัดผลการทำงาน (devguard stats)

รันคำสั่ง devguard stats เพื่อดูผลลัพธ์จากการใช้งานจริงครบทั้ง 3 หมวด:

╭─ 1. RTK Shell Compression Savings ─────────────────────────────────────────────╮
Total commands:    2446                 Tokens saved:      194.2K (38.6%)
Efficiency meter:  █████████░░░░░░░░░░░░░░░ 38.6%
╰────────────────────────────────────────────────────────────────────────────────╯
╭─ 2. Repositories (CodeGraph & ProjectMem) ─────────────────────────────────────╮
│ Repository                      Files  Symbols    Edges    Fixes Tokens Saved │
├────────────────────────────────────────────────────────────────────────────────┤
│ TOTAL (8 repos)                   655    16207    46092       51       134000 │
╰────────────────────────────────────────────────────────────────────────────────╯
╭─ 3. Verification & Workflow Quality (.verify/*.log) ───────────────────────────╮
│ Repository                   Verifies   Passed   Failed Pass Rate  Lines Saved │
├────────────────────────────────────────────────────────────────────────────────┤
│ TOTAL (5 repos)                   135      127        8       94%        22497 │
╰────────────────────────────────────────────────────────────────────────────────╯

การตรวจสุขภาพและซ่อมแซมตัวเอง (devguard doctor)

คำสั่ง devguard doctor ตรวจสอบ 8 จุดเสี่ยงของระบบ และซ่อมให้อัตโนมัติเมื่อใส่ --fix:

1. คราบการติดตั้ง tokless เดิม (รวมถึงล้าง ANTHROPIC_BASE_URL proxy ที่ค้างใน ~/.claude/settings.json)
2. Symlink ขาดหรือชื่อเก่าที่ค้างอยู่ใน ~/.local/bin
3. ปลั๊กอินที่ทำงานซ้ำซ้อนหรือตีกัน (caveman, ponytail, cavecrew)
4. ตำแหน่งไฟล์ MCP ของแต่ละ Agent
5. ปลั๊กอินและ Hook ของ RTK สำหรับ Google Antigravity
6. ความตรงกันของบล็อกกฎในไฟล์ของแต่ละ Agent เทียบกับ rules/core.md
7. เวอร์ชันของ CLI ทั้งหมดและเครื่องมือเสริม (ast-grep, xcbeautify, shellcheck)
8. memory sync ข้ามเครื่อง: hook .pth ชี้ไปที่ kit นี้, มี iCloud hub และไม่มี projectmem MCP ที่ยังรันโค้ด sync เก่า (ให้ปิดเปิด agent ใหม่ --fix ไม่ปิด process ให้)

การตั้งค่าโปรเจกต์อัตโนมัติ และซิงค์ความจำข้ามเครื่อง

ทุก Git repository ภายใต้ ~/Developer (ลึก 1–2 ชั้น) จะถูกตั้งค่าให้อัตโนมัติผ่าน 3 ช่องทาง: ตอนเปิด Claude Code, ตอนสั่ง cd เข้าโฟลเดอร์ใน zsh และการสแกนเบื้องหลังของ launchd ทุก 30 นาที โดยตรวจซ่อมทั้ง .gitignore, .codegraph/, .projectmem/config.toml, .git/hooks/post-commit และทะเบียนใน ~/.projectmem/projects.json

ซิงค์ความจำข้ามเครื่องผ่าน iCloud Drive (Multi-Mac CRDT Sync): เมื่อเปิดใช้งาน iCloud Drive ระบบจะซิงค์ความจำของ projectmem ข้ามเครื่องอัตโนมัติผ่าน ~/Library/Mobile Documents/com~apple~CloudDocs/devguard-sync/:

• แยกไฟล์ตามเครื่อง (Per-Device Node Files): แต่ละเครื่องเขียนลงไฟล์ของตัวเอง (nodes/<device_id>.jsonl, docs/<device_id>-PROJECT_MAP.md, docs/<device_id>-plan.md, global/nodes/<device_id>.json) จึงไม่เกิดไฟล์ซ้ำของ iCloud
• จับคู่โปรเจกต์ด้วย Git Root Commit (root-<sha12>): แม้ตั้งชื่อโฟลเดอร์คนละชื่อกันในแต่ละเครื่อง ระบบก็จับคู่เข้าถังความจำเดียวกันอัตโนมัติ
• แก้เลข Issue ชนกันขณะออฟไลน์: เรียงลำดับตามเวลาพร้อมผูก parent_issue_key และอัปเดต .projectmem/.current_issue ให้เองโดยข้อมูลไม่ปนกัน
• ซิงค์แบบ Real-time โดยไม่ต้องคอยรันเอง: ทำงานอัตโนมัติทุกครั้งที่ MCP อ่านหรือเขียนความจำ (ผ่าน .pth hook) รวมถึงตอน cd, ตอน launchd สแกน หรือสั่ง devguard sync
• ไม่ทำ event หายระหว่าง sync: การเขียน events.jsonl ใช้ lock ร่วมกัน event ที่เพิ่มเข้ามาระหว่าง sync จึงไม่หาย
• ตรวจว่า sync ตรงกันหรือยัง: devguard sync --check เทียบไฟล์ของทุกเครื่องทีละโปรเจกต์ และบอกชื่อเครื่องที่ยังขาด event ส่วน devguard status แสดงยอดรวม repo ที่ยังไม่มี commit และไม่มี remote จะไม่ถูก sync จนกว่าจะ commit ครั้งแรก เพื่อไม่ให้ repo คนละตัวที่ชื่อโฟลเดอร์ซ้ำกันรวมความจำกัน

การถอนการติดตั้ง (Uninstalling)

ทุกไฟล์ที่ถูกแก้ไขจะมีสำเนาสำรองอยู่ที่ ~/.agent-kit-backup/<เวลา>/ (เก็บชุดสำรองล่าสุดไว้สูงสุด 10 ชุดโดยอัตโนมัติ) และการสั่ง uninstall จะคืนสภาพไฟล์เดิมกลับมาทุกไบต์:

devguard uninstall --dry-run     # ดูสิ่งที่จะถูกลบโดยไม่ลบจริง
devguard uninstall               # ถอดกฎ, skill, hook และ MCP ออก (เก็บ CLI ของเครื่องมือไว้)
devguard uninstall --purge       # ลบ CLI ที่ devguard ติดตั้งให้ด้วย