你将得到什么

• 项目依赖里装好选定工具链（默认倾向 Oxlint + Oxfmt，也可 Biome / ESLint）
• 编辑器保存时自动 format / fix（如写入了 .vscode/settings.json）
• 根目录 AGENTS.md 出现 # Ultracite Code Standards 区块（供 Cursor / Claude Code / Codex 等读取）

课前准备

1. Node.js 22.18+（或 Bun）。官方 Setup 写明版本下限。
2. 一个带 package.json 的目录（可用 Vite/Next 脚手架，或空项目 npm init -y）。
3. 可选：已安装 Cursor 或 VS Code；本课 CLI 部分不依赖 IDE。

对照： 若 node -v 低于 22.18，先升级 Node，再继续。低于要求时 init 可能失败或行为异常。

node -v
# 对照结果示例：v22.18.0 或更高（你的输出以本机为准）

一、Ultracite 是什么（30 秒）

Ultracite 是面向「Agent 写代码」时代的零配置 lint/format 预设，一套命令可落到三种工具链之一：

装好后，日常主要靠保存时自动修；CLI 用 check / fix。详见 How does Ultracite work?。

二、交互式 init（推荐第一次跟做）

在项目根目录：

cd /path/to/your-project
npx ultracite@latest init

按提示选择：

1. Linter（未装过时可直接选 oxlint，或按团队习惯选 biome / eslint）
2. Package manager（npm / pnpm / bun / yarn…）
3. Frameworks（有则勾选，如 react next vue）
4. Editors（例如 cursor 或 universal）
5. Agents（至少勾选 universal，会写 AGENTS.md；若用 Claude Code 再勾 claude）
6. Hooks（本课第二课细讲；第一次可先跳过，或勾 cursor / claude）

init 会在改文件前问完所有问题。换 linter 时可能询问是否移除旧配置；不确定就先备份 .eslintrc* / biome.json 等。

对照结果（成功时常见迹象）

• 终端退出码 0，无红色报错栈
• package.json 的 devDependencies 出现 ultracite 以及所选 linter 相关包
• 根目录出现或更新了该工具链的配置文件（如 oxlint.config.ts / biome.json / eslint.config.mjs）
• 若选了 agents：AGENTS.md 含 # Ultracite Code Standards

# 快速自检：看 Ultracite 是否进了依赖
node -e "const p=require('./package.json'); console.log('ultracite' in (p.devDependencies||p.dependencies||{}))"
# 对照结果：true

# 看 Agent 规则块是否写入
rg -n "Ultracite Code Standards" AGENTS.md
# 对照结果：至少一行匹配（行号因文件而异）

三、非交互 / CI 友好写法（可抄）

无人值守或脚手架脚本可用官方推荐的 --yes：

npx ultracite init --yes --quiet --pm npm

指定工具链与 Agent（示例：Oxlint + 通用 AGENTS.md + Cursor 编辑器）：

npx ultracite init --yes --pm npm --linter oxlint --editors cursor --agents universal

指定 Biome，并打开 type-aware（会动 strictNullChecks，详见 Usage · Type-Aware）：

npx ultracite init --yes --pm npm --linter biome --type-aware --agents universal

注意： 传入 --yes 或任一 --pm / --editors / --agents 等旗标时，未点名的可选项会取默认（通常不会自动装 hooks / skill）。要 hooks 请显式加 --hooks …（下一课）。

对照结果

npx ultracite doctor
# 对照结果：检查通过或仅有可接受警告；若报 linter 版本过旧，按提示升级后再 doctor

四、Agent 规则怎么起作用

官方说明：规则写在 AGENTS.md；几乎所有编码 Agent 都会读它。init 若发现文件已存在，会把 Ultracite 内容放进以 # Ultracite Code Standards 开头的区块；重跑 init 只替换该区块，保留你自己的上文。

部分 Agent 需要额外一步（init 会做）：

来源：Agent Rules。

五、常见坑

1. Node 太旧 → 先升到 22.18+。
2. 仓库没有 package.json → 先 npm init -y 或用框架脚手架。
3. 旧 linter 配置残留 → check 可能仍跑到旧工具；按 init 提示清理，或再跑一次并允许移除。
4. 改了 AGENTS.md 里 Ultracite 区块 → 下次 init 会被覆盖；自定义规则写在该区块之外。

本课检查清单

• npx ultracite init（或带旗标的等价命令）成功结束
• npx ultracite doctor 无明显失败
• AGENTS.md 含 Ultracite 标准块（若选了 agents）
• 用编辑器打开任意 .ts/.tsx，保存后能看到格式变化（若装了 editors）

下一课：用 check / fix 修一批问题，并给 Cursor / Claude Code 挂上 after-edit hooks。