gas-best-practices

Claude Code skill — Google Apps Script best practices distilled from real production bugs.

Claude Code skill รวมแนวปฏิบัติที่ดีสำหรับ Google Apps Script — สังเคราะห์จาก bug จริงใน production

Use with Claude Code so that Claude follows production-tested patterns when writing or reviewing GAS code.

ใช้กับ Claude Code เพื่อให้ Claude แนะนำ/แก้ไขโค้ด GAS ตาม pattern ที่ผ่านการใช้งานจริงในระบบ production

📦 Installation / วิธีติดตั้ง

English

Option 1 — Mac / Linux (one-liner)

curl -fsSL https://raw.githubusercontent.com/kpcrmv4/gas-best-practices/main/install.sh | bash

Option 2 — Windows PowerShell (one-liner)

iwr -useb https://raw.githubusercontent.com/kpcrmv4/gas-best-practices/main/install.ps1 | iex

Option 3 — Manual git clone (any OS)

git clone https://github.com/kpcrmv4/gas-best-practices ~/.claude/skills/gas-best-practices

For Windows without ~:

git clone https://github.com/kpcrmv4/gas-best-practices "$HOME\.claude\skills\gas-best-practices"

Verify installation

ls ~/.claude/skills/gas-best-practices
# should show: SKILL.md, rules/, README.md, ...

Then restart Claude Code. The skill will auto-trigger when:

• Your project contains .clasp.json or appsscript.json
• You edit .gs or .js files in a clasp project
• You mention "Google Apps Script", "GAS", or "clasp" in a prompt

Check status

bash ~/.claude/skills/gas-best-practices/check.sh

Shows current version, rules count, and whether updates are available.

Update to latest

bash ~/.claude/skills/gas-best-practices/update.sh

Or manually:

cd ~/.claude/skills/gas-best-practices && git pull

Uninstall

rm -rf ~/.claude/skills/gas-best-practices

ภาษาไทย

วิธีที่ 1 — Mac / Linux (คำสั่งเดียวจบ)

เปิด Terminal แล้ววาง:

curl -fsSL https://raw.githubusercontent.com/kpcrmv4/gas-best-practices/main/install.sh | bash

วิธีที่ 2 — Windows PowerShell (คำสั่งเดียวจบ)

เปิด PowerShell (กด Win + X → Terminal/PowerShell) แล้ววาง:

iwr -useb https://raw.githubusercontent.com/kpcrmv4/gas-best-practices/main/install.ps1 | iex

วิธีที่ 3 — Manual ด้วย git clone (ทุก OS)

git clone https://github.com/kpcrmv4/gas-best-practices ~/.claude/skills/gas-best-practices

Windows ถ้าใช้ ~ ไม่ได้:

git clone https://github.com/kpcrmv4/gas-best-practices "$HOME\.claude\skills\gas-best-practices"

ตรวจสอบว่าติดตั้งสำเร็จ

ls ~/.claude/skills/gas-best-practices
# ต้องเห็น: SKILL.md, rules/, README.md, ...

จากนั้น ปิดและเปิด Claude Code ใหม่ เพื่อโหลด skill

Skill จะถูกเรียกใช้อัตโนมัติเมื่อ:

• โปรเจ็คที่เปิดอยู่มีไฟล์ .clasp.json หรือ appsscript.json
• คุณกำลังแก้ไฟล์ .gs หรือ .js ในโปรเจ็ค clasp
• คุณพิมพ์ prompt ที่มีคำว่า "Google Apps Script", "GAS", หรือ "clasp"

เช็คสถานะ + ดูว่ามีอัพเดทไหม

Mac / Linux:

bash ~/.claude/skills/gas-best-practices/check.sh

Windows PowerShell:

& "$HOME\.claude\skills\gas-best-practices\check.ps1"

จะแสดง version ปัจจุบัน, จำนวน rules, และบอกถ้ามี commit ใหม่ใน GitHub

อัพเดตเป็นเวอร์ชันล่าสุด

Mac / Linux:

bash ~/.claude/skills/gas-best-practices/update.sh

Windows PowerShell:

& "$HOME\.claude\skills\gas-best-practices\update.ps1"

หรือทำเองด้วย git:

cd ~/.claude/skills/gas-best-practices && git pull

หลังอัพเดต — restart Claude Code เพื่อโหลด skill เวอร์ชันใหม่

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

Mac / Linux:

rm -rf ~/.claude/skills/gas-best-practices

Windows PowerShell:

Remove-Item -Recurse -Force "$HOME\.claude\skills\gas-best-practices"

🔍 ทดสอบว่าใช้งานได้

หลัง install เสร็จ ลองเปิดโปรเจ็ค GAS แล้วถาม Claude:

"ช่วยตรวจ Code.gs หน่อย"

Claude ควรอ้างถึง pattern จาก skill นี้ (เช่น แนะนำให้ใช้ Result envelope, LockService, Logger.log boundary)

🤖 ใช้กับ AI tool อื่น (ไม่ใช่แค่ Claude Code)

Skill นี้ออกแบบให้ทำงานกับ Claude Code โดยตรง — แต่ เนื้อหา rule ใน rules/ เป็น markdown ธรรมดา ใช้กับ AI tool ตัวอื่นได้ทั้งหมด

Cursor / Windsurf / Cline

Clone repo เข้าไปในโปรเจ็ค หรือ copy ไฟล์ .cursorrules / .windsurfrules / .clinerules จาก repo นี้ไปวางใน root ของโปรเจ็คคุณ:

curl -O https://raw.githubusercontent.com/kpcrmv4/gas-best-practices/main/.cursorrules

แล้ว AI ของ tool นั้นจะอ่านอัตโนมัติเวลาคุณเปิดโปรเจ็ค (ต้อง clone repo ไว้ใกล้ ๆ เพื่อให้ AI access rules/*.md ได้)

ChatGPT / Claude.ai web / Gemini

ใช้ไฟล์ PROMPT.md ที่รวมทุก rule ในไฟล์เดียว:

1. ดาวน์โหลด: https://raw.githubusercontent.com/kpcrmv4/gas-best-practices/main/PROMPT.md
2. Copy เนื้อหาทั้งหมด
3. วางใน:
   • ChatGPT Custom GPT → Instructions field
   • ChatGPT Project → Project knowledge
   • Claude.ai Project → Project knowledge / custom instructions
   • Gemini Gem → Instructions

ขนาดประมาณ 4,700 บรรทัด (~110KB) — พอดีกับ context window ของโมเดลหลักทุกตัวในปัจจุบัน

PROMPT.md เป็นไฟล์ generate อัตโนมัติจาก build.sh — แก้เนื้อหาที่ rules/*.md แล้วรัน ./build.sh เท่านั้น

Gemini Code Assist / OpenCode

อ่านไฟล์ AGENTS.md อัตโนมัติ — clone repo เข้าโปรเจ็คก็ใช้ได้

GitHub Copilot

Copilot ไม่อ่าน external rule files แต่อ่าน .github/copilot-instructions.md ได้:

mkdir -p .github
curl -o .github/copilot-instructions.md \
  https://raw.githubusercontent.com/kpcrmv4/gas-best-practices/main/AGENTS.md

Aider

aider --read /path/to/gas-best-practices/AGENTS.md \
      --read /path/to/gas-best-practices/rules/spreadsheet-ops.md

Continue.dev

ใน .continue/config.json:

{
  "contextProviders": [
    {
      "name": "file",
      "params": {
        "filePath": "/path/to/gas-best-practices/PROMPT.md"
      }
    }
  ]
}

สรุปไฟล์ที่ใช้กับแต่ละ AI

เนื้อหา

Bugs จริงที่กฎเหล่านี้ป้องกัน

• 🐛 "ข้อผิดพลาดของบริการ: สเปรดชีต" ตอน range.setValues() บน template ที่มี merged cells → spreadsheet-ops.md
• 🐛 PassPercent = 500% เพราะ client คำนวณผิด server เชื่อตรง ๆ → spreadsheet-ops.md Rule #8
• 🐛 Signature preview broken image เพราะใช้ Drive URL ตรง ไม่ได้แปลงเป็น base64 → drive-ops.md Rule #3
• 🐛 Signature ทับแถวอื่นใน PDF เพราะรูปยังมี whitespace + ไม่ตั้ง anchor offset → pdf-generation.md Rule #4, #6
• 🐛 ปี dropdown หมดอายุปี 2026 เพราะ hardcode 2024-2026 → dynamic-dropdowns.md
• 🐛 Lock ค้าง 6 นาที เพราะลืม finally { releaseLock() } → lock-service.md Rule #4
• 🐛 PDF gen ของ 2 คนพร้อมกัน → temp sheet ชื่อชน → lock-service.md
• 🐛 "ไม่ได้รับอนุญาต (Permission denied): DriveApp" บน Google Workspace ของโรงเรียน/หน่วยงาน เพราะ setSharing(ANYONE_WITH_LINK) ถูก domain policy block → drive-ops.md Rule #4.1
• 🐛 เว็บแอปบนมือถือไม่ responsive เพราะ AI ใส่ viewport meta tag ใน .gs แทน .html → htmlservice-frontend.md Rule #1
• 🐛 เบอร์โทร 0812345678 กลายเป็น 812345678 เพราะ Sheets autoparse เป็น number — ต้อง setNumberFormat('@') หรือ prefix ' → spreadsheet-ops.md Rule #6.6
• 🐛 Date object ส่งจาก server มา client แล้วเป็น {} เพราะ google.script.run ไม่ serialize Date → spreadsheet-ops.md Rule #6.1
• 🐛 getUserMedia ใช้ไม่ได้ในเว็บแอป เพราะ GAS iframe block — ต้องย้าย frontend ไป GitHub Pages → external-frontend.md
• 🐛 fetch GAS แล้ว CORS error เพราะส่ง Content-Type: application/json (trigger preflight) — ต้องใช้ text/plain → external-frontend.md Rule #1
• 🐛 "ขออภัย ไม่สามารถเปิดไฟล์ได้ในเวลานี้" เวลามี Google หลายบัญชีในเครื่อง — แก้ด้วย ?authuser= หรือ /u/<n>/ → external-frontend.md Rule #8.1
• 🐛 Report รายวันส่งซ้ำ 3 ฉบับ เพราะรัน setup หลายรอบ → trigger ซ้อน 3 ตัว → triggers.md Rule #1
• 🐛 clasp push แล้วเว็บ /exec ยังเป็นโค้ดเก่า เพราะ deployment ตรึง version — ต้อง clasp deploy -i → deployment-versioning.md Rule #1-#2
• 🐛 งาน batch ตายกลางคันที่ 6 นาที ข้อมูลค้างครึ่งเดียว เพราะไม่มี checkpoint + continuation trigger → long-running-jobs.md Rule #2

โครงสร้าง repo

gas-best-practices/
├── SKILL.md             # entry point ที่ Claude อ่าน (มี frontmatter)
├── AGENTS.md            # entry point สำหรับ AI tool อื่น
├── README.md            # หน้าแรก GitHub
├── CHANGELOG.md         # ประวัติ version
├── LICENSE              # MIT
├── install.sh           # one-liner setup
├── install.ps1
├── build.sh             # generate PROMPT.md + sync .clinerules/.windsurfrules
├── rules/               # กฎแยกตามหัวข้อ — แต่ละไฟล์ standalone (23 ไฟล์)
│   ├── project-structure.md
│   ├── spreadsheet-ops.md
│   └── ...
├── evals/               # test prompts สำหรับวัดผล skill
│   └── evals.json
└── examples/            # โค้ดตัวอย่างที่ใช้ rule จริง
    └── web-app-skeleton/   # login + RPC + Lock ครบใน 5 ไฟล์

Contributing

PR ยินดีรับ! หลังแก้ rules/*.md หรือ .cursorrules ให้รัน ./build.sh เพื่อ regenerate PROMPT.md / .clinerules / .windsurfrules ก่อน commit (CI จะเช็คว่า sync กัน) — แต่ละ rule ทำตามแม่แบบ:

# <หมวด>

## Rule #N: <กฎสั้น ๆ ประโยคเดียว>

**Why:** <เหตุผล — bug จริงที่เคยเจอยิ่งดี>

### ✗ Bad
\`\`\`javascript
// โค้ดที่ทำให้พัง
\`\`\`

### ✓ Good
\`\`\`javascript
// แม่แบบที่ถูก
\`\`\`

**Edge case:** <ข้อยกเว้น ถ้ามี>

License

MIT