Graycen Notes

AI 辅助开发主流玩法：Claude Code 与 Cursor 完整指南

Fri, 26 Jun 2026 00:00:00 GMT

距离"AI 写代码"从概念变成日常，不过两三年时间。但真正高效用好这两款工具的开发者，和把它们当搜索引擎用的开发者，生产力差距已经拉开了一个数量级。这篇文章整理了当前最主流的工作流配置和使用范式——不是 README 级别的入门，而是已经被大量开发者验证过的实战方式。

一、先搞清楚定位：Cursor vs Claude Code，不是竞争是分工

很多人纠结该用哪个，但 2026 年社区里一个趋势越来越清晰：两者定位不同，主流用法是组合而非替换。

Cursor 脱胎于 VSCode，继承了完整的 IDE 体验——文件树、插件生态、调试器全都在。它的优势是低摩擦：边写边问、Tab 补全、多文件 diff 一览无余，视觉反馈非常直观，适合"局部快速迭代"场景。它的上下文控制和干预能力也更细腻，改哪行、不改哪行，开发者随时可以接管。

Claude Code 是个纯终端 Agent。没有编辑器界面，直接在你的 shell 里跑，可以读文件、改文件、跑命令、推代码。它的优势是深度自主：交给它一个跨越十几个文件的重构任务，或者"给我写完这个模块的测试"，它会自己规划、执行、验证，你去泡杯咖啡回来看结果。代价是黑盒感更强，适合"大块任务批量交付"场景。

一个被很多团队采用的分工模式是：Cursor 负责日常编写和探索，Claude Code 负责长会话的 Agentic 任务——比如跨模块重构、测试套件生成、框架迁移。这不是非此即彼，是术业专攻。

二、Claude Code 的核心玩法

1. CLAUDE.md：给 AI 装上项目记忆

如果只能做一件事提升 Claude Code 的输出质量，那就是写好 CLAUDE.md。

这个文件放在项目根目录，Claude Code 每次启动都会读取它，相当于给 AI 注入项目上下文。一个实用的 CLAUDE.md 通常包含：

项目概览：这是什么项目、主要技术栈、目录结构
代码规范：命名风格、注释要求、禁止使用的 API 或模式
开发约定：如何运行测试、构建命令、部署流程
常见陷阱：这个项目里有哪些"雷"，比如某个目录不能随便改、某个配置文件格式很特殊

示例片段：

# CLAUDE.md

## 项目简介
这是一个 Next.js 14 + Prisma + PostgreSQL 的 SaaS 应用。

## 技术约定
- 组件用函数式，不用 class component
- 数据库操作统一通过 `lib/db/` 下的 service 层，不在组件里直接调用 Prisma
- 测试用 Vitest，测试文件放在 `__tests__/` 目录

## 禁忌
- 不要修改 `prisma/migrations/` 下已有的迁移文件
- 不要在 server component 里引入客户端库

CLAUDE.md 支持层级：根目录是全局规则，子目录的 CLAUDE.md 覆盖局部规则。这意味着你可以给不同模块设置不同的 AI 行为规范。

2. Skills（技能）：固化你的高频流程

Skills 是 Claude Code 的"自定义斜杠命令"，本质是一段 Markdown 格式的指令模板，触发方式是 /skill名称。

官方生态和社区（如 SkillsMP）已经积累了大量开箱即用的 Skill：

Skill 示例	触发命令	用途
`implement`	`/implement`	按团队风格实现功能
`simplify`	`/simplify`	化简冗余代码
`test`	`/test`	生成单元测试
`pr-description`	`/pr-description`	自动生成 PR 描述
`security-review`	`/security-review`	安全漏洞扫描

Skills 存放在 .claude/skills/ 目录，每个 Skill 是一个 Markdown 文件，里面描述"当触发这个命令时，你应该做什么、遵循哪些规则"。写法比 Prompt 工程更结构化，可以版本控制、团队共享。

它解决的核心问题是：把你反复输入的那些复杂 Prompt，变成一个可复用、可维护的命令。

3. Hooks：在 AI 行为的关键节点插入你的逻辑

Hooks 是 Claude Code 的自动化机制，在 Agent 执行流程的特定事件上触发你的脚本。

主要的 Hook 事件：

PreToolUse：AI 准备调用某个工具（比如写文件、运行命令）之前触发
PostToolUse：工具执行完之后触发
Stop：Claude 完成一次回复时触发
Notification：Agent 需要用户注意时触发

实际用法举几个例子：

例1：防止 AI 直接改生产配置

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write",
      "command": "if echo '$CLAUDE_TOOL_INPUT' | grep -q 'production'; then exit 2; fi"
    }]
  }
}

返回退出码 2 会让 Claude 收到错误信息并停下来重新考虑。

例2：每次写完文件自动跑 lint

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write",
      "command": "npm run lint -- $CLAUDE_TOOL_OUTPUT_FILE 2>&1"
    }]
  }
}

这样 AI 写完代码，lint 错误会立刻反馈给它，进入自动修复循环，而不需要你手动盯着。

例3：Prompt Hook——用 AI 评估 AI

Hooks 还支持一种特殊的"Prompt Hook"，调用一个轻量模型来判断当前操作是否合规。比如在 AI 要删除文件时，先问一下"这个删除操作合理吗"，再决定是否放行。

4. Git Worktree：真正的并行开发

这是 Claude Code 社区里讨论度最高的工作流之一，原理并不复杂：Git Worktree 允许你从同一个仓库 checkout 出多个独立的工作目录，每个目录对应一个 branch，互不干扰。

配合 Claude Code 使用时，好处立刻出来了：

# 创建三个并行工作区
git worktree add ../project-feature-auth feature/auth
git worktree add ../project-fix-perf fix/performance
git worktree add ../project-refactor-api refactor/api-layer

# 在三个目录里分别启动 Claude Code
cd ../project-feature-auth && claude
cd ../project-fix-perf && claude
cd ../project-refactor-api && claude

三个 Claude Code 实例同时跑，做完全不同的任务，上下文互不污染，不会出现"AI 把 feature 分支的改动带进了 hotfix"这种问题。

关键优势：

每个 session 的上下文是干净的，AI 不会被其他任务的信息"污染"
多任务真正并行，不是伪并行
合并时走正常 Git 流程，冲突范围可控

适用场景：需要同时推进多个独立任务时——比如一边修 bug、一边写新功能、一边做重构，这三件事没有依赖关系，完全可以并行跑三个 Agent。

一个实用建议：worktree 的初始化成本不低（需要重新安装依赖、复制未追踪的配置文件），所以不值得为了 10 分钟能完成的任务专门开一个 worktree。对于预计需要 30 分钟以上的任务，开 worktree 的收益就很明显了。

5. Subagents 与 Agent Teams：让 AI 管理 AI

Claude Code 支持 Agent 委派：主 Agent 可以把子任务分配给 Subagent，由 Subagent 独立执行后返回结果。

Subagents 的适用场景是"一个大任务里有多个独立的子问题"：

"帮我给这个项目生成完整测试套件"
  → 主 Agent 拆分任务
  → Subagent A：处理 auth 模块的测试
  → Subagent B：处理 API 路由的测试
  → Subagent C：处理 util 函数的测试
  → 主 Agent：汇总结果

Agent Teams 是更进一步的协作模式——预先定义多个有不同角色的 Agent（比如一个 Planner、一个 Coder、一个 Reviewer），让它们以流水线方式协作完成任务。

什么时候值得用：任务能清晰拆分成互不依赖的子任务、且每个子任务足够重（单独跑一个 Agent 划算）时，委派才有收益。对于逻辑紧密相连的任务，拆分带来的协调开销反而会降低质量。

6. MCP：接入外部世界

MCP（Model Context Protocol）是连接 Claude Code 与外部工具的标准协议。通过配置 MCP Server，Claude Code 可以直接操作：

GitHub：搜索 PR、创建 issue、查看 diff
数据库：直接查询、生成迁移脚本并验证
文档系统：读取 Confluence、Notion 里的规范文档
监控系统：拉取 Sentry 错误、查 Grafana 指标
Slack：发送通知、搜索历史消息

配置方式是在 ~/.claude/claude_code_config.json 中声明 MCP Server：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "your_token" }
    }
  }
}

配置后，Claude Code 可以在完成编码后自动创建 PR、填写描述、关联 issue——整个提交流程几乎不需要人工操作。

三、Cursor 的核心玩法

1. Rules：项目级 AI 行为规范

Cursor 的 Rules（原 .cursorrules）是 2026 年改版后最重要的配置机制。现在的规则文件是 .mdc 格式，存放在 .cursor/rules/ 目录，支持 glob 模式按文件类型分别生效：

.cursor/rules/
├── general.mdc          # 全局规则
├── react-components.mdc # 只对 .tsx 文件生效
├── api-routes.mdc       # 只对 app/api/ 下的文件生效
└── test-files.mdc       # 只对 *.test.ts 生效

每个 .mdc 文件的 YAML 头部控制作用范围：

---
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

## React 组件规范

- 使用 TypeScript，所有 props 必须有类型定义
- 组件文件同时导出类型和组件
- 不使用 default export，统一用 named export
- CSS 用 Tailwind，不引入额外的 CSS 文件

这比全局一刀切的规则精准得多——写测试文件时用测试相关的规范，写 API 路由时切换到后端规范。

2. Agent 模式：从"补全"到"自主执行"

Cursor 的 Agent 模式（Composer）是它的核心功能。和普通的 Chat 不同，Agent 模式可以：

跨多个文件做修改
执行终端命令
读取报错信息并自动修复
在任务完成前持续循环，直到验证通过

2026 年的 Background Agents 更进一步——你不需要盯着 Cursor 界面，Agent 在后台跑，你可以继续做别的事，它完成后通知你。

实践中一个有效的工作流是"Plan → Execute → Review"三段式：

先让 Agent 输出执行计划，不执行，你审阅并修改
确认计划后，让它执行
执行完成后做 diff review，必要时局部回退

这在 Cursor 里通过"让 Agent 先描述它要做什么"来实现，避免 Agent 跑偏了你还不知道。

3. Skills（Cursor）：跨工具复用的能力单元

Cursor 也引入了 Skills 体系，格式采用 SKILL.md，和 Claude Code 的 Skills 格式相近，目的是让同一套能力描述在不同 AI 工具间可以复用。

这解决了一个现实问题：你精心写好的 Cursor 规则，换到 Claude Code 就得重写。Skills 的标准化格式让这个工作量降低了。

4. MCP：和 Claude Code 共用同一套工具生态

Cursor 对 MCP 的支持已经相当成熟，配置方式和 Claude Code 高度一致。这意味着你给 Claude Code 配好的 GitHub MCP Server、数据库 Server，在 Cursor 里改改配置就能复用。

6 个最值得配的 MCP Server（两款工具通用）：

MCP Server	用途
`github-mcp-server`	PR/Issue/代码搜索
`filesystem`	安全的文件系统访问
`postgres` / `sqlite`	数据库直接操作
`brave-search`	实时网络搜索
`sentry`	错误监控接入
`slack`	消息通知与搜索

四、两者通用的工作流原则

给 AI 的任务颗粒度要对

太大："帮我重构整个后端"——AI 会迷失方向，产出质量不稳定。太小："把这个变量名从 x 改成 count"——不值得调用 Agent，直接手写更快。

合适的颗粒度：一个功能点、一个模块的测试、一个具体的 bug 修复。能在一个上下文窗口内完成、有清晰的验收标准——这是给 AI 任务的黄金区间。

验收标准要前置

"帮我实现用户登录功能"不如"帮我实现用户登录功能，要求：通过 npm test 里的 auth 相关测试，错误信息要符合 docs/error-codes.md 的规范"。

前置验收标准，AI 才知道什么叫"完成"，才会主动验证而不是生成完就交差。

上下文污染是隐形杀手

一个 Claude Code session 跑太长之后，早期的错误信息、半途放弃的方向会慢慢干扰后续决策。认知到这一点后，适时开新 session 而不是在一个 session 里硬撑，是保持 AI 输出质量稳定的重要习惯。Worktree 模式的优势之一，就是每个任务天然有独立的干净上下文。

版本控制是安全网，不是事后补救

让 AI 大规模改代码之前，先 commit 当前状态——这几乎是所有重度用户的共识。不是不信任 AI，而是给自己保留随时回退的能力。用 AI 开发的节奏比手写快很多，出了问题如果没有 checkpoint，回溯的成本会非常高。

五、选型参考

不同场景下，哪款工具更适合：

场景	推荐工具	原因
日常功能开发、局部修改	Cursor	IDE 原生体验，干预灵活
大规模重构、跨模块任务	Claude Code	自主性强，适合长任务
多任务并行推进	Claude Code + Worktree	真并行，上下文隔离
需要接入外部系统（DB/GitHub）	两者均可（MCP 通用）	配置可复用
团队统一规范	Cursor Rules + CLAUDE.md	两者各有格式，可共存
移动端、无本地环境	Claude Code Web	Anthropic 已上线 Web 版

结语

工具本身的能力已经不是瓶颈了。把 CLAUDE.md 写清楚、把高频流程固化成 Skills、用 Hooks 关掉那些让 AI 反复犯错的"漏洞"、在需要并行时拉起 Worktree——这些配置投入一次，之后每次开发都在收益。

AI 编程工具的上限，越来越取决于你给它搭的环境，而不只是它本身的模型能力。

用 Cloudflare 全家桶做独立产品：Pages + Workers 零成本全栈方案

Fri, 26 Jun 2026 00:00:00 GMT

适合人群：想验证产品 MVP、不想在冷启动阶段花服务器钱的独立开发者

前言

很多独立开发者面临一个共同困境：产品的核心逻辑其实很简单，前端就能搞定大部分交互，但只要涉及「存用户数据」「发邮件」「生成订单号」这类事情，就不得不租一台服务器——每月几十到几百元，在产品还没验证市场前，这笔钱心里很虚。

Cloudflare 提供了一个优雅的解法：Pages + Workers + D1/KV，前后端都在 Cloudflare 边缘网络上，免费额度足够大多数早期产品撑过冷启动阶段。

APP推广页

实现效果： https://musiclab.pages.dev/zh

推广页脚手架： https://github.com/ayxworxfr/indie-launch-kit

无需编码，修改配置文件 5 分钟快速构建自己的 APP 宣传页

整体架构

用户浏览器
    │
    ▼
Cloudflare Pages（静态前端）
    │  核心业务逻辑在前端完成
    │  如：产品展示、定价计算、表单校验、 UI 交互
    │
    ▼  只在需要「持久化」或「安全操作」时才调用后端
Cloudflare Workers（轻量 API）
    │
    ├── D1（SQLite 数据库）  → 存用户信息、订单记录
    ├── KV（键值存储）        → 存会员码、邮件验证码、配置项
    ├── 邮件服务              → 对接 Resend / MailChannels
    └── 支付回调              → 对接 Stripe / Lemon Squeezy Webhook

核心原则：能在前端做的，绝不往后端甩。 Workers 只负责四件事：

写入 / 读取数据库（用户注册、订单记录）
生成唯一码（会员码、激活码、邀请码）
发送邮件通知（注册确认、付款成功）
处理第三方支付回调（验证签名、更新会员状态）

为什么这个组合适合独立开发者

费用对比

方案	月费估算	适合阶段
传统 VPS（2核4G）	¥50–200	成熟产品，流量稳定
Vercel + PlanetScale	$0–20	中期，有一定用户量
Cloudflare Pages + Workers	$0（免费额度内）	冷启动 / MVP 验证

Cloudflare 免费额度

服务	免费额度	说明
Pages	无限带宽，500次构建/月	静态托管完全够用
Workers	10万次请求/天	日活过万才需要付费
D1 数据库	5GB 存储，500万行读/天	早期产品完全够
KV 存储	10万次读/天，1000次写/天	存会员码足够

早期产品日活通常在几十到几百，上面的额度几乎永远用不完。

网速优势

Cloudflare 在全球 300+ 城市有节点，包括香港、东京
国内访问 Cloudflare Pages 比 GitHub Pages 稳定得多
Workers 在边缘执行，延迟极低（通常 < 50ms）

典型使用场景拆解

场景一：用户留资（邮件订阅）

前端：表单收集邮箱 + 前端校验格式
  ↓
Workers：写入 D1 数据库 + 发确认邮件
  ↓
完成：用户进入你的早期用户列表

Workers 代码示例：

// src/api/subscribe.ts
export async function handleSubscribe(request: Request, env: Env) {
  const { email } = await request.json();

  // 写入数据库
  await env.DB.prepare(
    'INSERT OR IGNORE INTO subscribers (email, created_at) VALUES (?, ?)'
  ).bind(email, new Date().toISOString()).run();

  // 发确认邮件（对接 Resend）
  await fetch('https://api.resend.com/emails', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${env.RESEND_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      from: 'noreply@yourdomain.com',
      to: email,
      subject: '订阅成功',
      html: '<p>感谢订阅，我们会在产品上线时第一时间通知你。</p>',
    }),
  });

  return new Response(JSON.stringify({ ok: true }), { status: 200 });
}

场景二：生成会员激活码

用户付款成功（Stripe Webhook 触发）
  ↓
Workers：验证支付签名 → 生成唯一激活码 → 存入 KV → 发邮件给用户
  ↓
用户收到激活码，在前端输入后验证（Workers 查 KV）

激活码生成示例：

// 生成 16 位大写字母+数字的激活码
function generateLicenseKey(): string {
  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
  const segments = Array.from({ length: 4 }, () =>
    Array.from({ length: 4 }, () => chars[Math.floor(Math.random() * chars.length)]).join('')
  );
  return segments.join('-'); // 格式：XXXX-XXXX-XXXX-XXXX
}

// 存入 KV，value 存用户邮箱，key 是激活码
await env.LICENSE_KV.put(licenseKey, email, {
  metadata: { plan: 'pro', activatedAt: null }
});

场景三：激活码校验

前端：用户输入激活码
  ↓
Workers：查 KV → 返回是否有效 + 已激活状态
  ↓
前端：解锁对应功能（如果核心功能在前端）

这套方案的边界和局限

诚实说，这套方案不是万能的，有几个明显限制：

适合做的事

静态内容展示（Landing Page、文档、博客）
轻量数据持久化（用户留资、订单记录、激活码）
简单 API（CRUD、邮件发送、Webhook 接收）

不适合做的事

实时性要求高：WebSocket 长连接（聊天、协同编辑），Workers 不擅长
复杂计算：Workers 有 CPU 时间限制（免费版 10ms），机器学习推理等跑不了
大文件处理：视频转码、图片处理，需要配合 Cloudflare R2 + Images
有状态会话：传统 Session 模式需要改成 JWT 或 KV 存 Token

安全注意事项

激活码校验、支付验证等必须在 Workers 里做，不能完全依赖前端
敏感密钥（API Key、数据库密码）通过 Workers 的 env 绑定，不要写死在代码里
前端的「解锁功能」只能做体验层，真正的权限控制要在服务端

快速上手

1. 初始化 Workers 项目

npm create cloudflare@latest my-api
cd my-api

2. 绑定 D1 数据库

# wrangler.toml
[[d1_databases]]
binding = "DB"
database_name = "my-app-db"
database_id = "xxxx-xxxx-xxxx"

3. 部署

# 部署 Workers
npx wrangler deploy

# 前端推送 GitHub 后 Cloudflare Pages 自动构建部署
git push origin main

4. 前端调用 Workers API

// 前端调用示例
const res = await fetch('https://my-api.your-name.workers.dev/subscribe', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: userEmail }),
});

总结

维度	评价
上手难度	⭐⭐⭐（比 VPS 简单，比纯前端复杂一点）
免费额度	⭐⭐⭐⭐⭐（早期产品几乎零成本）
国内访问速度	⭐⭐⭐⭐（比 GitHub Pages 强，比国内云差）
扩展性	⭐⭐⭐（够用，大规模需迁移）
适合场景	MVP 验证、个人工具、小型 SaaS 早期版本

一句话结论：如果你的产品核心是前端体验，后端只是做数据落地，Cloudflare Pages + Workers 是目前独立开发者冷启动阶段性价比最高的方案，没有之一。

项目地址

https://github.com/ayxworxfr/indie-launch-kit

参考链接

Skill 设计的本质：你不是在写指令，你是在塑造概率地形

Fri, 26 Jun 2026 00:00:00 GMT

核心论点

大多数人写 Skill 的心智模型是错的。

他们把 AI 当成一个听话的下属——"我写清楚了，它应该照做。" 然后困惑为什么 AI 读完 50 条规则，该犯的错一条不少。

真相是：LLM 不是在"遵守"你的规则，它是在一个概率空间中选择下一个 token。 你的 Skill 所做的，不是"下命令"，而是改变这个概率空间的地形——让正确的输出路径变成下坡路，让错误的输出路径变成需要翻越的高墙。

一旦你用这个心智模型重新看待 Skill 设计，很多"技巧"就不再是技巧，而是必然的推论。

一、为什么 90% 的 Skill 是废纸

先看一个反面教材：

## Rules
- 代码要有良好的错误处理
- 保持函数简短
- 注意性能
- 写清晰的注释

这四条规则看起来合理，但对 LLM 来说等于没写。原因有三：

第一，模糊即自由。 "良好的""简短的""注意"——这些词给了模型巨大的自由裁量空间。概率模型在有自由裁量空间时，会倾向于选择生成概率最高的路径——也就是最"平庸"的输出。

第二，声明不产生动作。 "保持函数简短"是一个状态描述，不是一个动作指令。模型读完会"知道"这件事，但知道 ≠ 执行。就像你知道该早睡，但你还是在刷手机。

第三，没有验证闭环。 规则写了，但没有检查点。模型没有任何机制"回头看看自己有没有遵守"。它是逐 token 生成的，注意力会随序列长度衰减，开头的规则到 3000 token 时已经是远处的微弱信号。

理解了这三个失败原因，解决方案就清晰了：消除模糊、制造动作、强制验证。

二、Skill 的物理结构（30 秒速览）

skill-name/
├── SKILL.md          # 唯一必需文件：元数据 + 执行指令
├── scripts/          # AI 可直接运行的脚本
├── references/       # 按需加载的参考文档（省 token）
└── assets/           # 模板和静态资源

SKILL.md 内部分两层：

┌──────────────────────────────────────────────┐
│  YAML Frontmatter（~100 tokens）              │ ← 常驻内存，用于触发判断
│  只回答一个问题："什么时候该用我？"              │
├──────────────────────────────────────────────┤
│  Markdown 正文（< 5000 tokens）               │ ← 触发后才加载
│  只回答一个问题："具体怎么做？"                 │
└──────────────────────────────────────────────┘

唯一需要记住的铁律： description 只写触发条件，绝不总结流程。否则 AI 会照着 description 干活，跳过你精心设计的正文。

# ❌ 把流程写进了 description —— AI 会跳过正文
description: 从稳定性、性能、可读性三维度审查代码，先列问题再给建议

# ✅ 只写触发条件
description: 当用户提交代码要求审查时使用

三、五个设计模式（核心章节）

以下不是"建议"，是从 LLM 的生成机制推导出的必然策略。

模式 1：动作化——把名词变成动词

LLM 看到动词时会"启动执行"，看到名词时会"表示理解"。

# ❌ 名词式（声明知识）
代码审查需要关注错误处理、边界条件和资源释放。

# ✅ 动词式（触发动作）
1. 搜索所有 async 函数，检查每一个是否有对应的 try-catch
2. 列出所有外部输入参数，逐个验证是否有 null/undefined 防护
3. 找到所有资源获取点（连接、文件句柄），确认每一个都有释放逻辑

区别不只是"更具体"——而是前者让模型停留在"理解"状态，后者把模型推入"执行"状态。这是两种完全不同的生成模式。

转化公式：

"注意 X" → "搜索所有 X 的实例，逐个检查 [具体标准]，列出不合格项"

模式 2：检查门——规则 × 检测 × 阻断

单独的规则是建议。规则 + 检测方法 + 阻断条件才是约束。

# ❌ 裸规则（模型会"忘记"）
函数不超过 30 行。

# ✅ 检查门（模型不得不执行）
## 函数长度检查
1. 统计每个函数的行数
2. 行数 > 30 的函数标记为 WARNING
3. 行数 > 50 的函数标记为 BLOCK

阻断条件：存在任何 BLOCK 级函数时，必须先完成拆分建议，才能继续后续步骤。

检查门三要素：

组件	作用	缺失后果
规则声明	定义标准	模型不知道标准
检测动作	强制模型去验证	模型"以为"自己遵守了
阻断条件	不通过不能继续	模型发现违规但跳过

模式 3：注意力锚点——对抗长序列遗忘

LLM 的注意力分布不均匀：开头和最近的内容权重最高，中段最容易被忽略。

这意味着在一个 3000 token 的 Skill 中，你在第 200 token 写的规则，到模型生成第 2000 个 token 时，影响力已经大幅衰减。

对策：三层防御架构

## Overview（开头声明——第一次曝光）
核心原则：先完成根因分析，再给修复建议。绝无例外。

## Steps（中段执行——第二次曝光）
### Step 3 完成后 → 中途自检
- [ ] 我是否已经完成了根因分析？
- [ ] 我是否在没有根因的情况下给了建议？
→ 如果后者为是，删除建议，回到 Step 2 重做。

## Final Checkpoint（结尾拦截——第三次曝光）
输出前最终确认：
- [ ] 根因分析是否有完整的因果链（至少 3 层 Why）
- [ ] 每条修复建议是否都能追溯到具体根因

未通过以上检查的内容不得出现在最终输出中。

同一条规则出现三次，但不是简单重复——开头是声明，中段是动作化的自检，结尾是阻断性的最终关卡。

模式 4：堵死逃逸路径——借口反驳表

LLM 有一种行为模式我称之为"优雅逃逸"：它会用看似合理的话术跳过困难步骤。

"这段代码比较简洁，没有明显问题。"  ← 翻译：我不想逐行检查
"建议用户自行验证。"              ← 翻译：我不确定，但不想承认
"其余部分保持不变。"              ← 翻译：我懒得输出完整内容

解法：把高频逃逸路径预置为"被禁止的输出模式"。

## 禁止的输出模式

以下表述如果出现在你的输出中，说明你正在偷懒，必须删除并重做：

| 禁止输出 | 应替换为 |
|:---|:---|
| "代码整体没有问题" | 列出你具体检查了哪些路径，每条的结论 |
| "建议用户自行测试" | 给出具体的测试命令和预期结果 |
| "其余保持不变" | 输出完整内容，或明确列出"未修改的部分"清单 |
| "可能是 X 导致的" | 给出验证是否为 X 的具体步骤 |

触发上述任何一条时，回退当前步骤重做。

这不是"提醒"模型——这是在概率空间中设置路障。当模型即将生成"代码整体没有问题"这个 token 序列时，它"知道"这条路径被明确标记为错误，概率会显著降低。

模式 5：渐进式信息投放——控制认知负荷

人的工作记忆容量是 7±2 项。LLM 的有效注意力窗口虽然更大，但同样遵循"信息越多，单条信息影响力越低"的规律。

策略：正文只放执行指令，背景知识按需加载。

## Step 2: API 兼容性检查

检查所有外部 API 调用是否符合 v3 规范。
详细规范见：[API v3 迁移指南](references/api-v3-migration.md)

仅加载你需要检查的部分，不要一次性读取整个文档。

Token 预算分配原则：

内容类型	位置	理由
触发条件	YAML description	必须始终在内存中
执行步骤 + 规则	SKILL.md 正文	触发后加载，是核心指令
参考文档 > 100 行	references/	按需加载，避免挤占注意力
代码模板	assets/	需要时再读取
自动化脚本	scripts/	AI 调用即可，无需理解全部

四、四种 Skill 骨架

选对骨架再填内容，事半功倍。

A. 工作流型

触发 → Step 1 → [产出物] → Step 2 → [产出物] → ... → 交付
                     ↓ 失败
               异常处理 / 回退 / 升级

用于： 步骤有明确先后依赖关系的任务。

B. 检查清单型

加载清单 → 逐项检查 → 标记状态（Pass/Warn/Block）→ 汇总 → 判断是否通过

用于： 确保覆盖面的审查型任务。

C. 生成器型

接收输入 → 校验输入完整性 → 按模板生成 → 校验输出质量 → 交付

用于： 从少量输入产出标准化文档。

D. 分析决策型

收集现象 → 强制多维度分析 → 根因推导 → 方案对比 → 输出结论
              ↑
         借口反驳表拦截偷懒

用于： 需要深度思考、防止浅层回答的场景。

五、完整示例：代码审查 Skill

将上述所有模式整合为一个可直接使用的 Skill：

---
name: code-review
description: >
  当用户提交代码片段或 diff 要求审查时使用。
  不适用于：代码生成、格式化、简单语法纠错。
---

# Code Review

## Core Principle
先理解意图，再逐项审查，最后结构化输出。
禁止只看前 20 行就开始下结论。禁止输出"整体不错"类空话。

## Steps

### Step 1: 全局理解
- 通读所有提交的代码
- 用一句话概括："这段代码的目的是 ____"
- 识别核心逻辑路径和数据流方向

### Step 2: 三维度审查

对每个维度执行检查门：

#### 稳定性
1. 搜索所有 async/await 调用 → 每个是否有 try-catch 或 .catch
2. 列出所有外部输入 → 每个是否有 null/undefined/类型校验
3. 找到所有资源获取点 → 每个是否有释放/关闭逻辑
4. 识别并发场景 → 是否有竞态条件风险

#### 性能
1. 识别所有循环 → 有无嵌套循环可降低复杂度
2. 搜索重复计算 → 是否可缓存或提取
3. 找到 I/O 操作 → 是否可批量化或并行化

#### 可读性
1. 统计每个函数行数 → > 30 行标记 WARNING，> 50 行标记 BLOCK
2. 检查所有命名 → 是否能脱离上下文理解含义
3. 搜索魔法数字和硬编码 → 逐个判断是否应提取为常量

### Step 2.5: 中途自检 ⚠️
- [ ] 三个维度是否每个都实际检查了（不是声明"已检查"，是有具体发现或"检查路径 X，未发现问题"）
- [ ] 是否有跳过的检查项？如有，补做。

### Step 3: 结构化输出

## Output Format

### 一句话总评
[具体描述主要问题类型和严重程度分布]

### 问题清单

| # | 维度 | 等级 | 位置 | 问题 | 修复建议 |
|:--|:-----|:-----|:-----|:-----|:---------|

等级定义：
- P0: 会导致运行时错误或安全漏洞，必须修
- P1: 影响可维护性或性能，强烈建议修
- P2: 代码质量优化，可选

### 亮点（如有）
[具体指出设计优秀之处及原因]

## Forbidden Outputs

| 禁止出现的表述 | 替代方案 |
|:---|:---|
| "代码整体质量不错" | 指出具体的优秀设计，或不写亮点部分 |
| "建议添加更多测试" | 给出具体应该测试哪些路径 |
| "可能存在性能问题" | 量化：什么输入规模下、什么复杂度、影响多大 |
| "其他部分没有问题" | 列出你检查了哪些路径，每条的结论 |

## Escalation
- 代码超过 500 行 → 建议用户分批提交
- 发现安全漏洞 → 置为 P0，输出开头加 🚨 标记
- 无法判断业务意图 → 先提问确认，不要猜测后审查

## Final Gate
输出前扫描自己的回答：
1. 是否触发了 Forbidden Outputs 中的任何一条？→ 删除重写
2. 每个维度是否至少有一条具体发现（含"已检查无问题"）？→ 补全
3. 每条修复建议是否具体到可直接实施？→ 模糊的要补充代码示例

六、Skill 写完后的调试循环

写完不是结束，是开始。 好的 Skill 是调试出来的，不是设计出来的。

调试方法：对抗性测试

写完后，故意用以下方式测试你的 Skill：

1. 给它一个极简输入，看它会不会偷懒
2. 给它一个超长输入，看中段规则是否被遗忘
3. 给它一个边界 case，看异常处理是否触发
4. 连续跑 3 次同样的输入，看输出一致性

迭代公式

每次 AI 犯错 → 分析属于哪种失败模式：

模糊导致的？     → 加量化标准
没执行？         → 把名词改成动词
中段忘了？       → 加中途检查点
找借口跳过了？   → 加进 Forbidden Outputs
超出能力了？     → 加 Escalation 条件

记录每次修改的原因（哪怕一行注释），三个月后你会感谢自己。

七、设计原则速查

#	原则	一句话
1	单一职责	一个 Skill 只做一件事
2	动作优先	动词 > 名词，指令 > 声明
3	量化一切	能写数字的地方绝不写形容词
4	三层防御	开头声明 + 中途自检 + 结尾拦截
5	堵死逃逸	预判偷懒路径，设为禁止输出
6	渐进披露	正文 < 500 行，背景知识按需加载
7	人工兜底	超出能力时停止，不要硬撑
8	持续调试	每次翻车都是下一条规则的来源

结语

回到开头的核心论点：

你不是在"告诉" AI 做什么。你是在一个高维概率空间中——用动作指令降低正确路径的生成阻力，用检查门和阻断条件抬高错误路径的生成成本，用注意力锚点确保关键约束在整个生成过程中持续施加影响。

这就是 Skill 设计的全部本质。

当你用这个视角审视自己写的每一行指令时，你会自然地问出正确的问题：

"这句话会改变概率分布吗？还是只是让我自己感觉写了？"
"这条规则有检查机制吗？还是全靠 AI 自觉？"
"3000 token 之后，这条约束还能被'感知到'吗？"

能诚实回答这三个问题的人，写出的 Skill 不会差。

Markdown Extended Features

Wed, 01 May 2024 00:00:00 GMT

GitHub Repository Cards

You can add dynamic cards that link to GitHub repositories, on page load, the repository information is pulled from the GitHub API.

::github{repo="Fabrizz/MMM-OnSpotify"}

Create a GitHub repository card with the code ::github{repo="<owner>/<repo>"}.

::github{repo="saicaca/fuwari"}

Admonitions

Following types of admonitions are supported: note tip important warning caution

:::note Highlights information that users should take into account, even when skimming. :::

:::tip Optional information to help a user be more successful. :::

:::important Crucial information necessary for users to succeed. :::

:::warning Critical content demanding immediate user attention due to potential risks. :::

:::caution Negative potential consequences of an action. :::

Basic Syntax

:::note
Highlights information that users should take into account, even when skimming.
:::

:::tip
Optional information to help a user be more successful.
:::

Custom Titles

The title of the admonition can be customized.

:::note[MY CUSTOM TITLE] This is a note with a custom title. :::

:::note[MY CUSTOM TITLE]
This is a note with a custom title.
:::

GitHub Syntax

[!TIP] The GitHub syntax is also supported.

> [!NOTE]
> The GitHub syntax is also supported.

> [!TIP]
> The GitHub syntax is also supported.

Spoiler

You can add spoilers to your text. The text also supports Markdown syntax.

The content :spoiler[is hidden ayyy]!

The content :spoiler[is hidden **ayyy**]!

Expressive Code Example

Wed, 10 Apr 2024 00:00:00 GMT

Here, we'll explore how code blocks look using Expressive Code. The provided examples are based on the official documentation, which you can refer to for further details.

Expressive Code

Syntax Highlighting

Regular syntax highlighting

console.log('This code is syntax highlighted!')

Rendering ANSI escape sequences

ANSI colors:
- Regular: [31mRed[0m [32mGreen[0m [33mYellow[0m [34mBlue[0m [35mMagenta[0m [36mCyan[0m
- Bold:    [1;31mRed[0m [1;32mGreen[0m [1;33mYellow[0m [1;34mBlue[0m [1;35mMagenta[0m [1;36mCyan[0m
- Dimmed:  [2;31mRed[0m [2;32mGreen[0m [2;33mYellow[0m [2;34mBlue[0m [2;35mMagenta[0m [2;36mCyan[0m

256 colors (showing colors 160-177):
[38;5;160m160 [38;5;161m161 [38;5;162m162 [38;5;163m163 [38;5;164m164 [38;5;165m165[0m
[38;5;166m166 [38;5;167m167 [38;5;168m168 [38;5;169m169 [38;5;170m170 [38;5;171m171[0m
[38;5;172m172 [38;5;173m173 [38;5;174m174 [38;5;175m175 [38;5;176m176 [38;5;177m177[0m

Full RGB colors:
[38;2;34;139;34mForestGreen - RGB(34, 139, 34)[0m

Text formatting: [1mBold[0m [2mDimmed[0m [3mItalic[0m [4mUnderline[0m

Editor & Terminal Frames

Code editor frames

console.log('Title attribute example')

<!-- src/content/index.html -->
<div>File name comment example</div>

Terminal frames

echo "This terminal frame has no title"

Write-Output "This one has a title!"

Overriding frame types

echo "Look ma, no frame!"

# Without overriding, this would be a terminal frame
function Watch-Tail { Get-Content -Tail 20 -Wait $args }
New-Alias tail Watch-Tail

Text & Line Markers

Marking full lines & line ranges

// Line 1 - targeted by line number
// Line 2
// Line 3
// Line 4 - targeted by line number
// Line 5
// Line 6
// Line 7 - targeted by range "7-8"
// Line 8 - targeted by range "7-8"

Selecting line marker types (mark, ins, del)

function demo() {
  console.log('this line is marked as deleted')
  // This line and the next one are marked as inserted
  console.log('this is the second inserted line')

  return 'this line uses the neutral default marker type'
}

Adding labels to line markers

// labeled-line-markers.jsx
<button
  role="button"
  {...props}
  value={value}
  className={buttonClassName}
  disabled={disabled}
  active={active}
>
  {children &&
    !active &&
    (typeof children === 'string' ? <span>{children}</span> : children)}
</button>

Adding long labels on their own lines

// labeled-line-markers.jsx
<button
  role="button"
  {...props}

  value={value}
  className={buttonClassName}

  disabled={disabled}
  active={active}
>

  {children &&
    !active &&
    (typeof children === 'string' ? <span>{children}</span> : children)}
</button>

Using diff-like syntax

+this line will be marked as inserted
-this line will be marked as deleted
this is a regular line

--- a/README.md
+++ b/README.md
@@ -1,3 +1,4 @@
+this is an actual diff file
-all contents will remain unmodified
 no whitespace will be removed either

Combining syntax highlighting with diff-like syntax

  function thisIsJavaScript() {
    // This entire block gets highlighted as JavaScript,
    // and we can still add diff markers to it!
-   console.log('Old code to be removed')
+   console.log('New and shiny code!')
  }

Marking individual text inside lines

function demo() {
  // Mark any given text inside lines
  return 'Multiple matches of the given text are supported';
}

Regular expressions

console.log('The words yes and yep will be marked.')

Escaping forward slashes

echo "Test" > /home/test.txt

Selecting inline marker types (mark, ins, del)

function demo() {
  console.log('These are inserted and deleted marker types');
  // The return statement uses the default marker type
  return true;
}

Word Wrap

Configuring word wrap per block

// Example with wrap
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

// Example with wrap=false
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

Configuring indentation of wrapped lines

// Example with preserveIndent (enabled by default)
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

// Example with preserveIndent=false
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

Collapsible Sections

// All this boilerplate setup code will be collapsed
import { someBoilerplateEngine } from '@example/some-boilerplate'
import { evenMoreBoilerplate } from '@example/even-more-boilerplate'

const engine = someBoilerplateEngine(evenMoreBoilerplate())

// This part of the code will be visible by default
engine.doSomething(1, 2, 3, calcFn)

function calcFn() {
  // You can have multiple collapsed sections
  const a = 1
  const b = 2
  const c = a + b

  // This will remain visible
  console.log(`Calculation result: ${a} + ${b} = ${c}`)
  return c
}

// All this code until the end of the block will be collapsed again
engine.closeConnection()
engine.freeMemory()
engine.shutdown({ reason: 'End of example boilerplate code' })

Line Numbers

Displaying line numbers per block

// This code block will show line numbers
console.log('Greetings from line 2!')
console.log('I am on line 3')

// Line numbers are disabled for this block
console.log('Hello?')
console.log('Sorry, do you know what line I am on?')

Changing the starting line number

console.log('Greetings from line 5!')
console.log('I am on line 6')

Simple Guides for Fuwari

Mon, 01 Apr 2024 00:00:00 GMT

Cover image source: Source

This blog template is built with Astro. For the things that are not mentioned in this guide, you may find the answers in the Astro Docs.

Front-matter of Posts

---
title: My First Blog Post
published: 2023-09-09
description: This is the first post of my new Astro blog.
image: ./cover.jpg
tags: [Foo, Bar]
category: Front-end
draft: false
---

Attribute	Description
`title`	The title of the post.
`published`	The date the post was published.
`description`	A short description of the post. Displayed on index page.
`image`	The cover image path of the post.<br/>1. Start with `http://` or `https://`: Use web image<br/>2. Start with `/`: For image in `public` dir<br/>3. With none of the prefixes: Relative to the markdown file
`tags`	The tags of the post.
`category`	The category of the post.
`draft`	If this post is still a draft, which won't be displayed.

Where to Place the Post Files

Your post files should be placed in src/content/posts/ directory. You can also create sub-directories to better organize your posts and assets.

src/content/posts/
├── post-1.md
└── post-2/
    ├── cover.png
    └── index.md

Markdown Example

Sun, 01 Oct 2023 00:00:00 GMT

An h1 header

Paragraphs are separated by a blank line.

2nd paragraph. Italic, bold, and monospace. Itemized lists look like:

this one
that one
the other one

Note that --- not considering the asterisk --- the actual text content starts at 4-columns in.

Block quotes are written like so.

They can span multiple paragraphs, if you like.

Use 3 dashes for an em-dash. Use 2 dashes for ranges (ex., "it's all in chapters 12--14"). Three dots ... will be converted to an ellipsis. Unicode is supported. ☺

An h2 header

Here's a numbered list:

first item
second item
third item

Note again how the actual text starts at 4 columns in (4 characters from the left side). Here's a code sample:

# Let me re-iterate ...
for i in 1 .. 10 { do-something(i) }

As you probably guessed, indented 4 spaces. By the way, instead of indenting the block, you can use delimited blocks, if you like:

define foobar() {
    print "Welcome to flavor country!";
}

(which makes copying & pasting easier). You can optionally mark the delimited block for Pandoc to syntax highlight it:

import time
# Quick, count to ten!
for i in range(10):
    # (but not *too* quick)
    time.sleep(0.5)
    print i

An h3 header

Now a nested list:

First, get these ingredients:
- carrots
- celery
- lentils
Boil some water.

Dump everything in the pot and follow this algorithm:

 find wooden spoon
 uncover pot
 stir
 cover pot
 balance wooden spoon precariously on pot handle
 wait 10 minutes
 goto first step (or shut off burner when done)

Do not bump wooden spoon or it will fall.

Notice again how text always lines up on 4-space indents (including that last line which continues item 3 above).

Here's a link to a website, to a local doc, and to a section heading in the current doc. Here's a footnote [^1].

[^1]: Footnote text goes here.

Tables can look like this:

size material color

9 leather brown 10 hemp canvas natural 11 glass transparent

Table: Shoes, their sizes, and what they're made of

(The above is the caption for the table.) Pandoc also supports multi-line tables:

keyword text

red Sunsets, apples, and other red or reddish things.

green Leaves, grass, frogs and other things it's not easy being.

A horizontal rule follows.

Here's a definition list:

apples : Good for making applesauce. oranges : Citrus! tomatoes : There's no "e" in tomatoe.

Again, text is indented 4 spaces. (Put a blank line between each term/definition pair to spread things out more.)

Here's a "line block":

| Line one | Line too | Line tree

and images can be specified like so:

Inline math equations go in like so: $\omega = d\phi / dt$. Display math should get its own line and be put in in double-dollarsigns:

$$I = \int \rho R^{2} dV$$

$$ \begin{equation*} \pi =3.1415926535 ;8979323846;2643383279;5028841971;6939937510;5820974944 ;5923078164;0628620899;8628034825;3421170679;\ldots \end{equation*} $$

And note that you can backslash-escape any punctuation characters which you wish to be displayed literally, ex.: `foo`, *bar*, etc.

Include Video in the Posts

Tue, 01 Aug 2023 00:00:00 GMT

Just copy the embed code from YouTube or other platforms, and paste it in the markdown file.

---
title: Include Video in the Post
published: 2023-10-19
// ...
---

<iframe width="100%" height="468" src="https://www.youtube.com/embed/5gIf0_xpFPI?si=N1WTorLKL0uwLsU_" title="YouTube video player" frameborder="0" allowfullscreen></iframe>

YouTube

Bilibili