课前确认

• 已完成上一课 init，npx ultracite doctor 基本健康
• 仍在同一项目根目录操作

npx ultracite doctor
# 对照结果：无「致命」失败项；版本过新可能仅警告

一、先制造一点「脏」代码（便于看见效果）

任选一个会被工具链扫到的源文件（示例用 src/demo.ts；没有就新建）：

mkdir -p src
cat > src/demo.ts <<'TS'
export const greet = ( name:string )=>{
  var x = 1
  console.log( "hi" , name )
  return x
}
TS

上面故意写了多余空格、var、格式混乱等；具体哪些规则会报警取决于你选的工具链与预设，以你本机 check 输出为准。

二、只检查、不改文件：`check`

npx ultracite check

对照结果

• 终端打印若干 diagnostics（路径 + 规则名 + 说明）
• 若存在未修复问题，进程通常以非 0 退出（便于 CI）
• 磁盘上的 src/demo.ts 内容不变

也可以只查部分路径：

npx ultracite check src/demo.ts

官方说明：未知旗标会传给底层 linter；不属于工具处理的文件（如 Dockerfile）会被跳过而不是整次失败。见 Usage · CLI。

三、自动修：`fix`

npx ultracite fix

再打开 src/demo.ts：格式与可安全自动修复的问题应已收敛。

对照结果示例（概念性）

npx ultracite check src/demo.ts
# 对照结果：该文件相关问题明显减少或清零；若仍有项，属于需人工/Agent 处理的规则

不安全修复（可能改运行时行为）

npx ultracite fix --unsafe

• Biome：应用其 unsafe fix（文档举例：noSubstr 等到 slice() 的改写）
• Oxlint：走 oxlint --fix-dangerously
• ESLint 工具链：该旗标会被忽略并警告

来源：Usage · Fixing Code。

（可选）把剩余问题交给本机 Agent CLI

需已安装并登录 Claude Code 或 Codex CLI：

npx ultracite fix --claude
# 或
npx ultracite fix --codex

官方行为摘要：先跑普通 autofix → 按文件把剩余诊断交给 Agent（有重试与复检）→ 仍有问题则非 0 退出。Agent 权限受限（Claude：acceptEdits；Codex：workspace-write sandbox）。详见同页 AI-Powered Fixing。

四、给 Agent 挂 hooks（改完自动 fix）

Hooks 与 --agents（写规则）是两套配置。hooks 在 Agent 编辑文件之后跑项目内的：

npx ultracite fix --hook

安装（在已 init 的项目上追加）

# 按你实际使用的工具勾选；可多选
npx ultracite init --hooks cursor claude

官方会写入例如：

完整列表见 Agent Hooks。

对照结果

# Cursor 用户示例
test -f .cursor/hooks.json && echo "cursor hooks present"
# 对照结果：cursor hooks present

# 或 Claude Code
rg -n "ultracite fix" .claude/settings.json .cursor/hooks.json 2>/dev/null
# 对照结果：至少一处匹配到 fix/--hook

行为要点（跟做时心里有数）

1. 默认只修 Agent 刚改的那个文件（从 hook payload 读路径）。
2. hook 模式会跳过「未使用 import」类清理，避免 Agent 刚加、尚未使用的 import 被删掉。
3. 修不掉的问题：不少宿主在退出码 2 + stderr 时会把信息塞回 Agent，让它继续改。

五、和 CI / 提交钩子的关系（了解即可）

init 可用 --integrations husky lefthook lint-staged pre-commit 把检查接到 Git 流程；本课不强制配置。需要时查 Setup 旗标表。

日常建议：

# 提交前本地
npx ultracite check

本课检查清单

• npx ultracite check 能跑出可读诊断
• npx ultracite fix 后示例文件变干净（或仅剩需人工的项）
• （可选）init --hooks … 后对应 hooks 文件存在
• 在 Cursor/Claude Code 里让 Agent 改一个文件，确认保存后格式被自动收束

延伸阅读

• 迁移旧 ESLint/Prettier/Biome：https://www.ultracite.ai/docs/migrate
• 升级：npx ultracite@latest upgrade
• 规则哲学与 Agent 列表：https://www.ultracite.ai/agents

恭喜：你已经有一套「人 + Agent」共用的 lint/format 基线。之后换 Agent 产品时，优先保证 AGENTS.md 与 hooks 仍指向同一套 ultracite CLI。