Claude Skills替代传统团队文档实践

Claude Skills替代传统团队文档实践 | 前端进阶之旅

Full translation

完整中文译文

为什么用传统文档的开发者，最后都转向了 AI 指令

每个开发者都知道文档的悖论：你花几个小时写文档解释代码库怎么工作，然后你的队友（或未来的自己）直接忽略这些文档，转身问 ChatGPT。AI 给出一个看起来合理但完全错误的答案，因为它不知道你的特定模式。于是你花一小时调试，发现 AI 编造了你的认证流程，然后你再写更多文档，而这些文档没人会读。

我通过用 Claude skills 替换大部分传统文档打破了这个循环：结构化指令教会 AI 如何理解这个具体的代码库。

结果是：AI 遵循我的架构而不是猜测。贡献者之间的代码保持一致。而且文档真正被使用，因为消费者是一台读完所有内容的机器。

The Problem: AI Without Context

现代 AI 编码助手在通用任务上能力惊人。要求 Claude "添加一个 REST endpoint"，你会得到干净、可工作的代码。但它不会匹配你的模式。

在我的代码库中，API 路由使用带有特定验证模式的 Elysia。数据库查询通过 Drizzle ORM 并采用特定的事务风格。后台任务使用带有步级检查点的 Inngest。认证检查遵循特定的中间件模式。

没有上下文，Claude 生成的代码可以工作，但不属于这个地方。它可能在 Elysia 代码库中使用 Express 约定。它写原生 SQL 而不是使用 ORM。它把业务逻辑放在 API 路由中，而不是服务函数中。

代码通过类型检查，但造成了架构漂移。随着时间推移，你的代码库变成了冲突模式的大杂烩。有些是人写的，有些是 AI 生成的，都略有不同。

What Claude Skills Are

Claude skill 是 .claude/skills/ 中的一个 markdown 文件，编码了特定的模式或工作流。当 Claude 遇到相关任务时，它读取 skill 并遵循规定的方法。

这是添加 API 路由 skill 的一个简化示例：

---
name: skill-name
description: A description of when to trigger this skill, e.g. whenever backend changes
---

# Adding API Routes (Elysia)

## Pattern

All API routes follow this structure:

1. Define route in `src/server/routes/`
2. Use Elysia's type-safe body validation
3. Check auth via `auth.api.getSession({ headers: request.headers })`
4. Return consistent response shapes: `{ data }` on success, throw on error
5. Register route in `src/server/api.ts`

## Example

// src/server/routes/bookmarks.ts
import { Elysia, t } from "elysia";
import { auth } from "@/lib/auth";
import { db } from "@/lib/db";
import { bookmarks } from "@/lib/db/schema";

export const bookmarkRoutes = new Elysia({ prefix: "/bookmarks" })
  .get("/", async ({ request }) => {
    const session = await auth.api.getSession({
      headers: request.headers,
    });
    if (!session) throw new Error("Unauthorized");

    const results = await db
      .select()
      .from(bookmarks)
      .where(eq(bookmarks.userId, session.user.id));

    return { data: results };
  });

Anti-patterns

Do NOT use Express-style req, res parameters
Do NOT put database queries directly in route handlers for complex logic
Do NOT skip auth checks on protected routes


这不是传统意义上的文档。它是为 AI 读者优化的指令集。显式的模式、具体的例子、清晰的反模式。

## Why This Works Better Than Documentation

### 消费者真的会读它

人类开发者浏览文档、搜索需要的代码片段、复制粘贴然后继续。Claude 每次读整个 skill。它不跳过章节。它不假设已经知道。每条指令都被遵循。

### 它强制一致性

当三个开发者在一个代码库工作时，你会得到三种略有不同的模式。当这些开发者用 Claude skills 工作时，你会得到一个模式精确复制三次。

要求 Claude "添加用户资料，包含数据库表、API endpoint 和设置页面"。它读相关的数据库 skill、API 路由 skill 和 UI 模式 skill，然后生成匹配你代码库中每项约定的代码。

### 它捕获架构漂移

不用 skills，Claude 做出合理猜测。有 skills，Claude 遵循显式规则。任何单次交互中差异都很微妙，但累积数周后会复合。

我见过有些代码库，6 个月的 AI 辅助开发造成了混乱。有些文件使用一种状态管理方法，其他使用不同的方法，auth 模式跨路由不一致。Skills 防止了这一点。

### 它编码为什么，不只是什么

好的 skills 解释推理：

Why Inngest over BullMQ

We use Inngest for background jobs because:

Step-level checkpointing (failed step retries from that step, not the beginning)
No Redis dependency
Built-in AgentKit for AI agent workflows
Durable webhooks (Stripe events never lost)

Do NOT suggest switching to BullMQ, Temporal, or custom queue implementations.


这防止 Claude "有帮助地"建议可能破坏架构的替代方案。

## The Skills I Actually Use

经过几个月的构建和精化后，以下是价值最高的 skills 类别：

**Stack 特定模式**。如何添加 API 路由、数据库表、React hooks、UI 组件。这些是使用最多的 skills，因为它们覆盖添加功能的日常工作。

**集成指南**。Stripe webhooks 如何流经 Inngest，认证如何跨 web 和移动工作，RAG 管道如何连接文档上传到 AI 聊天。这些编码了最难正确处理的复杂跨切面关注点。

**反模式列表**。不要做什么。这些出乎意料地有效，因为 Claude 最常见的失败模式是生成可工作但违反架构决策的代码。

**工作流 skills**。更高级别的常见多步任务 skills："添加完整功能"（schema + API + hooks + UI）、"设置新集成"、"创建电子邮件模板"。这些编排多个低级别模式。

所有这些 skills 都随 Eden Stack 提供。

## Model Context Protocol (MCP): The Other Half

Skills 教 Claude **如何**写代码。MCP（Model Context Protocol）servers 教 Claude **如何**与外部服务交互。

不是手动创建 Neon 数据库、复制连接字符串、创建 Stripe 产品、复制 API 密钥、设置 Resend、配置 PostHog，我为每个服务都有 MCP servers。Claude 直接调用它们。

我在配置文件中描述我的项目

Claude 读取配置

Claude 调用 MCP servers 创建数据库、支付产品、电子邮件域、分析项目

环境变量自动填充

过去花 60 多分钟在仪表板间上下文切换的工作，现在只需约 5 分钟描述我想要什么。

## The Agentic Mindset Shift

以这种方式工作从根本上改变了我对开发的思考。

**之前**：我写代码。我偶尔要求 AI 帮助。AI 给出通用建议，我调整。

**之后**：我描述意图。AI 使用我的精确模式实现。我审查并调整方向。

心智模型是管理一个初级开发者团队。他们快速、刀子嘴豆腐心，擅长模式匹配。但他们需要清晰的指令（skills）、工具访问权（MCP）和质量保证（审查）。

这如何实际发挥作用的一些实践例子：

**添加功能**：我描述"添加收藏功能，让用户可以书签项目"。Claude 读数据库 skill，创建表。读 API skill，创建 endpoints。读 hooks skill，创建 React Query hooks。读 UI skill，创建组件。全部匹配现有模式。

**修复 bug**：我描述"移动端登出后会话仍然保持"。Claude 检查认证 skill，追踪 signOut 流程，识别问题，修复它。

**重构**：我描述"对话列表在 100+ 项时很慢"。Claude 读 UI 模式 skill，知道添加虚拟化。读 API skill，添加分页。用适当缓存更新 React Query hook。

在每种情况下，输出与代码库其余部分一致，因为 skills 编码了模式。

坦率地说限制：

Skills 不能替代思考。Claude 遵循模式很好，但它不做架构决策。你仍需决定**构建什么**。Skills 帮助**如何构建**。

Skills 需要维护。当你改变模式时，需要更新 skill。我被编码旧约定的过时 skills 坑过。

复杂跨切面关注点很难 skill 化。"添加 API 路由" 的 skill 很直接。"重新设计认证流程支持 SAML" 的 skill 太复杂且依赖上下文，无法编码。

你仍需读输出。Claude 是一个快速、非常字面意义上有能力的开发者。它精确做你说的，不是你想要的。审查 AI 生成的代码是必不可少的。

## 如何在自己的代码库中尝试这种方法

**从最常见的任务开始**。你最常构建什么？API endpoints？React 组件？数据库迁移？首先为那个写一个 skill。

**从最常见的任务开始**。你最常构建什么？API endpoints？React 组件？数据库迁移？首先为那个写一个 skill。

**包含具体例子**。抽象描述不能很好地工作。展示你想要的**精确**代码模式。

**包含具体例子**。抽象描述不能很好地工作。展示你想要的**精确**代码模式。

**列举反模式**。当没有上下文时 Claude 会弄错什么？将这些编码为显式"不要做"规则。

**列举反模式**。当没有上下文时 Claude 会弄错什么？将这些编码为显式"不要做"规则。

**保持 skills 专注**。一个 skill 一个关注点。不要写涵盖所有内容的超大 skill。Claude 可以每任务读多个 skills。

**保持 skills 专注**。一个 skill 一个关注点。不要写涵盖所有内容的超大 skill。Claude 可以每任务读多个 skills。

**迭代**。你的首个 skill 会很平庸。使用 10 次看到 Claude 偏离之后，你会将它精化成坚实的东西。

**迭代**。你的首个 skill 会很平庸。使用 10 次看到 Claude 偏离之后，你会将它精化成坚实的东西。

如果你宁愿从 30+ 条生产测试过的 skills 开始，已经写在你现成的代码库中，Eden Stack 包含本文章描述的所有 skills。

目标不是替代人类判断。是消除 AI 能够生成的（给予完美上下文）和它实际生成的（猜测你的约定）之间的差距。Skills 缩小了差距。

文档存在于可能读它的人类。Skills 存在于总是读它们的 AI。在一个 AI 写越来越多生产代码的世界中，优化 AI 读者不只是务实的。它是对你代码库一致性的最高杠杆投资。

Magnus Rødseth 构建 AI 原生应用，是 Eden Stack 的创造者，一个生产就绪的启动工具包，包含 30+ 条 Claude skills 编码的 AI 原生 SaaS 开发生产模式。

一些评论可能仅对登录访客可见。登录查看所有评论。

有更多行动，你可以考虑阻止此人 和/或 举报滥用