setup-ts-deep-modules
ติดตั้ง dependency-cruiser เข้า repo TypeScript เพื่อให้แต่ละ package เป็น deep module — implementation ถูกซ่อนไว้ใน subfolder เข้าถึงได้ผ่านไฟล์ entry point เท่านั้น สำหรับให้ user เรียกใช้เอง
- License 许可
- MIT
- 最近更新
- 2026-10-22
- Stars
- ★ 5
- Forks
- 1
01 前言 Front Matter
- name
- setup-ts-deep-modules
- description
- ติดตั้ง dependency-cruiser เข้า repo TypeScript เพื่อให้แต่ละ package เป็น deep module — implementation ถูกซ่อนไว้ใน subfolder เข้าถึงได้ผ่านไฟล์ entry point เท่านั้น สำหรับให้ user เรียกใช้เอง
- disable-model-invocation
- true
02 资源文件 1
- 脚本dependency-cruiser.config.cjs3.6 KB
03 SKILL.md 正文
Setup TS Deep Modules
ทำให้ทุก package ใน repo นี้เป็น deep module (module ที่มีพฤติกรรมเยอะแต่ interface เล็ก): พฤติกรรมจำนวนมากอยู่หลัง interface ที่เล็ก พื้นผิว public ของ package คือ entry points ของมัน — ไฟล์ที่อยู่ที่ root ของ package — และทุกอย่างใน subfolder ถูกซ่อนไว้ skill นี้ติดตั้ง dependency-cruiser พร้อมกฎที่ทำให้ entry points เป็นทางเข้าเดียว แล้วพิสูจน์ว่ากฎกัดจริง
สำหรับ vocabulary (deep module, interface, seam, depth) ให้รัน skill /codebase-design — และใช้ภาษาของมันตลอดทั้งงาน
รูปทรงที่กฎนี้บังคับ
src/packages/
<name>/
index.ts ← an entry point (public). Import this from outside.
client.ts ← another entry point. Packages may expose SEVERAL.
lib/ ← implementation: hidden from outside, free to import each other.
tests/ ← co-located tests + fixtures (a subfolder, so private).
พื้นผิว public คือไฟล์ที่ root ของ package — ไม่ใช่ index.ts ตัวใดตัวหนึ่งที่ถูกกำหนดไว้ ตามธรรมเนียมแล้ว implementation อยู่ใน lib/ และ test อยู่ใน tests/ ทำให้ทุก package มีรูปทรงสองโฟลเดอร์เหมือนกันหมด แต่ตัวกฎเองเป็นกฎทั่วไป: อะไรก็ตามใน subfolder ไหนก็ตามถือเป็น private ดังนั้นคุณไม่ต้องไปขยาย config เพื่อเพิ่มโฟลเดอร์เลย
กฎสี่ข้อ ทั้งหมดเป็นระดับ error:
- Entry-point boundary — code ที่อยู่นอก package (app code หรือ package อื่น) import ได้เฉพาะ entry points ของ package นั้น (ไฟล์ที่ root) ห้ามแตะอะไรใน subfolder เด็ดขาด
- Intra-package freedom — ไฟล์ภายใน package เดียวกัน import กันเองได้อย่างอิสระ
- Tests through the entry points — ไฟล์ใต้
<pkg>/tests/import ได้เฉพาะ entry points ของ package ใด ๆ กับ fixture ในtests/ของตัวเอง แต่ห้าม import internals ใน subfolder ของ package ไหนทั้งนั้น (แม้แต่ของตัวเอง) integration test ข้าม package ทำได้ แต่ deep import ทำไม่ได้ - No cycles — ห้ามมี dependency cycle
Entry points ไม่ใช่ barrel เพราะพื้นผิว public คือไฟล์ root ทุกไฟล์ package หนึ่งจึงเปิด entry point เล็ก ๆ ได้หลายตัว (index.ts, client.ts, server.ts) แทนที่จะบีบทุกอย่างผ่าน index.ts ยักษ์ตัวเดียว barrel file ที่ re-export ทั้ง subtree เป็นสิ่งที่ไม่แนะนำ — ทำ entry point ให้เล็กและซ่อน implementation ไว้ใน subfolder
ส่วนเรื่อง layering (package ไหนพึ่ง package ไหนได้บ้าง) เป็นคนละประเด็น และถูกทิ้งไว้เป็น stub แบบ comment ใน config ให้ repo นี้เติมเอง
ขั้นตอน
1. ตรวจสภาพแวดล้อม
- Package manager —
pnpm-lock.yaml→ pnpm,yarn.lock→ yarn,bun.lockb→ bun, นอกนั้นคือ npm ใช้ตัวที่ตรวจพบกับทุกคำสั่งด้านล่าง (pnpm/yarn/npm run/bunx) - Packages root — ถ้ามี
src/ให้ใช้src/packagesไม่งั้นใช้packagesถ้า repo มีธรรมเนียมอื่นที่ชัดเจนอยู่แล้ว ให้ยืนยันตัวเลือกกับ user ก่อน - Config เดิม — เช็คว่ามีไฟล์
.dependency-cruiser.*อยู่ไหม ถ้ามี ห้ามเขียนทับ: ให้ merge กฎสี่ข้อกับ options เข้าไป แล้วบอก user ว่าเพิ่มอะไรไปบ้าง
เสร็จเมื่อ: รู้ครบทั้ง package manager, packages root และสถานะของ config เดิม
2. ติดตั้ง dependency-cruiser
ติดตั้ง dependency-cruiser เป็น devDependency ด้วย package manager ที่ตรวจพบ
เสร็จเมื่อ: dependency-cruiser อยู่ใน devDependencies
3. เขียน config
คัดลอก dependency-cruiser.config.cjs ไปไว้ที่ root ของ repo ในชื่อ .dependency-cruiser.cjs ตั้ง PACKAGES_ROOT เป็น root ที่ตรวจพบในขั้น 1 ตัวกฎอิงจากความลึกของ path และไม่ผูกกับนามสกุลไฟล์ จึงไม่ต้องปรับอะไรอย่างอื่นอีก
เสร็จเมื่อ: .dependency-cruiser.cjs มีอยู่จริงพร้อม PACKAGES_ROOT ที่ถูกต้อง และมีกฎ forbidden ครบทั้งสี่ข้อ
4. ต่อเข้ากับชุด check
- เพิ่ม script
lint:boundaries:depcruise <packages-root>(หรือdepcruise src) - พับมันเข้าไปในคำสั่ง check รวมของ repo — ตัวที่รัน typecheck อยู่แล้ว (เช่น script
check/ci/validate) ห้ามแตะtsconfigหรือเพิ่ม path alias - ถ้าไม่มี script รวม ให้เพิ่ม
lint:boundariesแล้วบอก user ให้เอาไปใส่ใน CI
เสร็จเมื่อ: lint:boundaries มีอยู่และรันเป็นส่วนหนึ่งของคำสั่งเดียวกับ typecheck
5. Scaffold package ตัวอย่าง
สร้าง <packages-root>/example/ แบบ commit เข้า repo เป็น template ให้คัดลอกไปใช้:
index.ts— entry point ตัวหนึ่ง export ฟังก์ชันหนึ่งตัวที่ delegate ไปยังไฟล์ภายใน (เพื่อให้เห็นชัดว่า package นี้ deep จริง ไม่ใช่แค่ pass-through)lib/impl.ts— ไฟล์ภายในที่อยู่ใน subfolder ถูก import โดยindex.tsและเข้าถึงจากภายนอกไม่ได้tests/example.test.ts— import เฉพาะ../index(entry point) และ assert กับฟังก์ชัน public
บอก user ว่านี่คือ template ตั้งต้นไว้คัดลอกหรือลบทิ้งก็ได้
เสร็จเมื่อ: package ตัวอย่างมีอยู่จริง เปิดพฤติกรรมผ่าน entry point ที่ root และซ่อน impl ไว้ใน subfolder
6. พิสูจน์ว่ากฎกัดจริง
นี่คือเกณฑ์ความสำเร็จของ skill ทั้งตัว — config ที่ไม่ fail ตอนมีการละเมิดคือของไร้ค่า
- รัน
lint:boundariesมันต้องผ่านบน example ที่สะอาด - เพิ่ม deep import ชั่วคราวเข้าไปใน
tests/example.test.ts(เช่นimport { thing } from "../lib/impl") แล้วรันlint:boundariesอีกครั้ง — มันต้อง fail ด้วยกฎtests-through-entrypoints - เอา deep import ออก รันอีกรอบ — มันต้องผ่าน
เสร็จเมื่อ: คุณเห็นด้วยตาว่าผ่าน แล้ว fail บน deep import แล้วกลับมาผ่านอีกครั้ง ถ้าขั้น 2 ไม่ fail แปลว่ากฎยังต่อไม่ถูก — แก้ให้เสร็จก่อนจบงาน
7. บันทึกธรรมเนียมเป็นเอกสาร
เขียน README.md ในโฟลเดอร์ packages (<packages-root>/README.md) — วางไว้ข้าง ๆ packages ที่มันกำกับ — ครอบคลุม: layout แบบ src/packages/<name>/ (entry points ที่ root, lib/ สำหรับ implementation, tests/ สำหรับ test), กติกา "import ผ่าน entry points ของ package (ไฟล์ที่ root) เท่านั้น" และวิธีรัน lint:boundaries ระบุชัด ๆ ว่าไม่แนะนำ barrel file — ให้เปิด entry point เล็ก ๆ หลายตัวแทนการ re-export ทั้ง subtree ผ่าน index ตัวเดียว เขียนให้กระชับ: snippet ให้คัดลอก บวกกฎสี่ข้อ ข้อละหนึ่งย่อหน้า
จากนั้นเพิ่ม context pointer ชี้ไปหามันจากไฟล์ agent-instructions ของ repo — CLAUDE.md ถ้ามี ไม่งั้นใช้ AGENTS.md (สร้าง AGENTS.md ถ้าไม่มีทั้งคู่) บรรทัดเดียวก็พอ เช่น Packages are deep modules — see [src/packages/README.md](./src/packages/README.md) before adding or importing one. นี่แหละคือสิ่งที่ทำให้ agent ค้นพบกฎ boundary เอง แทนที่จะเดินสะดุดมัน
เสร็จเมื่อ: <packages-root>/README.md มีอยู่จริงและไม่แนะนำ barrel และ CLAUDE.md/AGENTS.md ของ repo มีลิงก์ไปหามัน
หมายเหตุ
- back-reference
$1ใน config (การ match แบบ group ของ dependency-cruiser) คือสิ่งที่ทำให้ package เข้าถึง internals ของตัวเองได้ในขณะที่คนนอกทำไม่ได้ — อย่าคลี่มันออกเป็นกฎแยกรายต่อ package - public กับ private ตัดสินด้วยความลึก: ไฟล์ที่ root ของ package คือ entry points ส่วนอะไรก็ตามใน subfolder คือ private โฟลเดอร์ตามธรรมเนียมคือ
lib/(implementation) กับtests/แต่กฎไม่ได้ hardcode ชื่อพวกนี้ — subfolder ไหนก็ private หมด ดังนั้นเพิ่มโฟลเดอร์ใหม่ก็ไม่ต้องแก้ config เลย ส่วนการเพิ่ม entry point ก็แค่เพิ่มไฟล์ที่ root — ไม่ต้องมี barrel - Packages เป็นแบบแบน: มีลูกชั้นเดียวใต้ root โดยตรง internals ของ package จะซ้อนลึกแค่ไหนก็ได้ แต่ package ห้ามมี package อื่นซ้อนอยู่ข้างใน
- ใช้
.cjs(ไม่ใช่.js) เพื่อให้module.exportsของ config ทำงานได้แม้ใน repo ที่เป็น"type": "module"
04 同仓库更多 Skills
writing-great-skills
อ้างอิงสำหรับการเขียนและแก้ไข skill ให้ดี — คำศัพท์และหลักการที่ทำให้ skill ทำงานได้อย่างคาดเดาได้
teach
สอน skill หรือ concept ใหม่ให้ผู้ใช้ ภายใน workspace นี้
handoff
บีบอัดบทสนทนาปัจจุบันให้เป็นเอกสาร handoff สำหรับให้ agent ตัวอื่นรับช่วงต่อ
grilling
ซักถาม user อย่างไม่ปรานีเกี่ยวกับแผนหรือ design ใช้เมื่อ user อยาก stress-test แผนก่อนลงมือสร้าง หรือใช้ trigger phrase ใด ๆ ที่มีคำว่า 'grill'
grill-me
บทสัมภาษณ์แบบไม่ปล่อยผ่าน เพื่อทำให้ plan หรือ design คมขึ้น
obsidian-vault
ค้นหา สร้าง และจัดการ note ใน Obsidian vault ด้วย wikilinks และ index note ใช้เมื่อ user อยากหา สร้าง หรือจัดระเบียบ note ใน Obsidian