菜单
Prefer Bun-native APIs, else Node built-ins with the node: prefix. Use when importing a Node built-in (fs, path, child_process, crypto, os, util), reading or writing files, spawning a process, or choosing between a Bun and a Node API.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Add a new shared workspace package under packages/*. Use when creating a new @packages/<name>, whether a bundled library other workspaces import or a build-only script package that runs during a build.
Orient in this repo: which file to edit for a change, how a change ripples across the stack, and how to search the code. Use at the start of a task in an unfamiliar area, or before a cross-cutting change.
Icebox a raised-but-undecided concern instead of forcing a plan-or-dismiss call: record it with no verdict so the context survives. Use when a review, PR, audit, or eval surfaces something real-maybe that should not be scheduled or closed yet, or when the user says to icebox or park an item.
Add a typed Hono API endpoint or WebSocket route: router, OpenAPI docs, validation envelope, and RPC client wiring. Use when adding or modifying routes in api/hono.
Start, restart, and verify the ZeroStarter dev stack. `bun run dev` serves portless named `.localhost` URLs (branch-prefixed in a worktree); resolve them with `bunx portless get`. Use when asked to run the app, when the API returns NOT_FOUND for routes that exist in source, or before browser testing.
Verify a frontend or UI change in a real browser. Use after any change to web/next pages, components, or styles, before opening or updating a PR, or when an end-to-end flow needs checking.
| name | runtime-apis |
| description | Prefer Bun-native APIs, else Node built-ins with the node: prefix. Use when importing a Node built-in (fs, path, child_process, crypto, os, util), reading or writing files, spawning a process, or choosing between a Bun and a Node API. |
Two rules, in order:
Bun.file, Bun.write, Bun.spawn/Bun.spawnSync, Bun.Glob, Bun.YAML, Bun.serve.node: prefix. Reach for a Node built-in with the protocol prefix: import { join } from "node:path", require("node:fs"). Never the bare form: write node:path, not a bare path specifier.The prefix is mandatory even in Bun-only code: it marks the import as a built-in rather than an npm package, so resolution is identical under every runtime.
Bun.* exists only on the Bun runtime. These areas run on Node, so node: is load-bearing and Bun.* is a crash, not a style choice:
| Area | Runtime | Rule |
|---|---|---|
packages/cli/** | Node | node: only. Published to npm, launched via npx (bin shebang #!/usr/bin/env node); Bun.* breaks every npx user. |
web/next/** | Node | node: only. Next.js on Vercel. |
packages/env/** | Node + Bun | node: only. Imported by both web (Node) and api (Bun); stays portable. |
.github/workflows/* (actions/github-script) | Node | require("node:..."). |
Bun-first applies to Bun-only files: .github/scripts/*.ts and packages/scripts/src/*.ts (bun x.ts). The CLI test files run under bun test but mirror the CLI's node: style on purpose.
| Need | Bun (preferred) | Node fallback |
|---|---|---|
| read file text | await Bun.file(p).text() | node:fs readFileSync |
| read file bytes | await Bun.file(p).arrayBuffer() | node:fs readFileSync |
| write file | await Bun.write(p, data) | node:fs writeFileSync |
| file exists | await Bun.file(p).exists() | node:fs existsSync |
| spawn a process | Bun.spawn / Bun.spawnSync | node:child_process |
| glob | new Bun.Glob(pattern) | (none) |
| parse YAML | Bun.YAML.parse | (none) |
| serve HTTP/WS | Bun.serve | @hono/node-server (Vercel only) |
node:)node:path, node:os, node:util, node:crypto, node:readline/promises, and the directory/sync parts of node:fs (existsSync in sync code, mkdirSync, mkdtempSync, readdirSync, rmSync). Bun ships no Bun.path/Bun.os, so node: is the idiomatic API for these even in pure-Bun files.
No bare (unprefixed) built-in specifier may exist anywhere. This prints nothing when clean:
The alternation $B is the full Node built-in list, so a new bare import cannot slip through; extend it only if Node ships a new module.
B='assert|async_hooks|buffer|child_process|cluster|console|constants|crypto|dgram|diagnostics_channel|dns|domain|events|fs|http|http2|https|inspector|module|net|os|path|perf_hooks|process|punycode|querystring|readline|repl|stream|string_decoder|sys|timers|tls|trace_events|tty|url|util|v8|vm|wasi|worker_threads|zlib'
rg -n "from ['\"]($B)(/[a-z_]+)?['\"]|require\(['\"]($B)(/[a-z_]+)?['\"]\)" -g '!**/dist/**' -g '!.claude/worktrees/**' --hidden
The full per-file inventory lives in index.md: every file, its runtime, and the node: modules it imports. Regenerate it when the surface changes:
rg -n "node:[a-z/_]+" -g '!**/dist/**' -g '!.claude/worktrees/**' --hidden