1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

project/
├── .claude/
│   ├── settings.json            # 项目设置
│   ├── CLAUDE.md                # 项目级指令（核心）
│   ├── .mcp.json                # 项目级 MCP 服务器配置
│   ├── rules/                   # 模块化规则文件
│   │   ├── code-style.md        # 代码风格
│   │   ├── testing.md           # 测试规范
│   │   └── security.md          # 安全要求
│   ├── agents/                  # 自定义子代理
│   │   ├── code-reviewer.md
│   │   └── debugger.md
│   ├── skills/                  # 自定义技能
│   │   └── fix-issue/
│   │       └── SKILL.md
│   ├── worktrees/               # Git Worktree 目录
│   └── docs/                    # AI 生成的文档目录

1
2
3
4
5
6
7
8

# 构建
- 安装：`npm install`
- 测试：`npm test`
- Lint：`npm run lint`

# 规范
- TypeScript strict 模式
- 提交消息使用 Conventional Commits

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

# 项目：[项目名]
[一句话描述]。技术栈：[列出关键技术]。

# 构建与测试
- 安装：`pnpm install`
- 开发：`pnpm dev`
- 构建：`pnpm build`
- 测试全部：`pnpm test`
- 测试单个：`pnpm test -- path/to/test`
- 类型检查：`pnpm typecheck`
- Lint：`pnpm lint`

# 代码规范
- 使用 ES modules（import/export）
- 函数参数 >3 个时使用对象参数
- 错误处理使用 AppError 类（@src/lib/errors.ts）
- API 路径 kebab-case，JSON 属性 camelCase

# 架构
- 状态管理：Zustand（不是 Redux）
- ORM：Drizzle（不是 Prisma）
- API：tRPC

# 工作流
- **IMPORTANT**: 修改代码后运行 `pnpm typecheck`
- **NEVER**: 不要修改 migrations/ 下的已有文件
- 提交遵循 Conventional Commits

# 压缩指令
When compacting, preserve:
- 修改过的文件完整列表
- 测试命令和结果
- 未完成的任务

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# 构建命令
- 开发：`pnpm dev`（端口 3000）
- 构建：`pnpm build`
- 测试：`pnpm test`（Vitest）
- E2E：`pnpm e2e`（Playwright）

# 代码规范
- 函数式组件 + hooks
- Tailwind CSS（不用 CSS modules）
- 导入顺序：React → 第三方 → 本地 → 类型 → 样式

# 组件结构
- 页面：`src/app/`（Next.js App Router）
- 组件：`src/components/`
- 参考：`src/components/ui/Button.tsx`

# 测试
- 优先运行单个测试文件
- UI 变更后截图对比验证

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

---
paths:
  - "src/api/**/*.ts"
  - "lib/**/*.ts"
  - "src/**/*.{ts,tsx}"       # brace expansion：同时匹配 .ts 和 .tsx
---

# API 开发规范
- 所有 API 端点必须包含输入验证
- 使用标准错误响应格式

1
2
3
4
5
6
7

{
  "statusLine": {
    "type": "command",
    "command": "npx -y ccstatusline@latest",
    "padding": 0
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

┌─────────────────────────────────────────────┐
│  1. 任务描述                                 │
│     做什么？（一句话清晰描述）                 │
├─────────────────────────────────────────────┤
│  2. 上下文                                   │
│     相关文件：@path/to/files                  │
│     参考模式：@path/to/example                │
│     背景信息：为什么要做这个                    │
├─────────────────────────────────────────────┤
│  3. 约束                                     │
│     不能做什么 / 必须满足什么                   │
│     "不引入新依赖"、"保持向后兼容"              │
├─────────────────────────────────────────────┤
│  4. 验证标准                                  │
│     怎么确认做对了？                           │
│     "运行 npm test"、"截图对比"               │
└─────────────────────────────────────────────┘

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

实现 [功能描述]。

上下文：
- 相关文件：@path/to/relevant/files
- 参考已有模式：@path/to/similar/implementation

要求：
1. [具体要求 1]
2. [具体要求 2]
3. [具体要求 3]

验证：
- 运行 `npm test` 确保所有测试通过
- 运行 `npm run typecheck` 确保无类型错误

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

修复 [问题描述]。

复现步骤：
1. [步骤 1]
2. [步骤 2]
3. [出现错误]

错误信息：
[粘贴完整错误信息或堆栈跟踪]

期望行为：[描述正确行为]

请：
1. 找到根因
2. 写一个能复现问题的失败测试
3. 修复问题
4. 确认测试通过

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

审查 @path/to/file 的以下方面：
- 安全漏洞（注入、XSS、认证问题）
- 边界情况处理
- 性能问题
- 与项目现有模式的一致性

对每个问题给出：
1. 问题严重度（Critical / Warning / Suggestion）
2. 具体位置（文件名和行号）
3. 修复建议

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

为 @src/utils/date.ts 添加 formatRelativeTime 函数。

要求：
- 输入 Date，输出 "刚刚"、"3 分钟前"、"2 小时前"、"昨天"、"3 天前" 等
- 超过 7 天返回 YYYY-MM-DD 格式

验证：
1. 先为以上每种情况编写测试用例
2. 实现函数
3. 运行 `npm test -- formatRelativeTime`
4. 运行 `npm run typecheck`
5. 所有通过后告诉我结果

1
2
3
4

specs/001-feature-name/
├── spec.md      ← WHAT：功能需求（用户故事、验收标准、边界情况）
├── plan.md      ← HOW：技术方案（架构设计、数据结构、接口定义）
└── tasks.md     ← DO：原子任务（逐步执行指令，每个任务改一个文件）

1
2
3

> 我想构建 [功能描述]。用采访模式对我进行详细提问，
> 帮我生成一份 spec.md，包含：用户故事、验收标准、边界情况。
> 不要写任何技术实现细节。

1
2
3
4

> @specs/001-feature/spec.md
> 基于这份需求规范，生成技术方案 plan.md。
> 技术栈约束：[TypeScript / React / PostgreSQL]
> 包含：目录结构、核心数据模型、接口定义、实施阶段。

1
2
3

> @specs/001-feature/spec.md @specs/001-feature/plan.md
> 将技术方案分解为原子任务列表 tasks.md。
> 要求：每个任务只改一个文件，测试先行（奇数任务写测试，偶数任务写实现）。

1
2

> @specs/001-feature/tasks.md
> 执行任务 T001-T006。严格按 TDD 顺序：先写测试（必须失败），再写实现（使测试通过）。

1
2
3
4
5
6

我想构建 [简要描述]。用 AskUserQuestion 工具对我进行详细采访。

问我关于技术实现、UI/UX、边界情况、顾虑和权衡的问题。
不要问显而易见的问题，深入挖掘我可能没有考虑到的困难部分。

持续采访直到我们覆盖了所有方面，然后把完整的需求规格写入 SPEC.md。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

我想开发一款独特的小游戏，但具体做什么、怎么做还没想好。

请你作为游戏策划顾问，用苏格拉底式提问法帮我从零厘清思路。要求：

- 必须使用 AskUserQuestion 工具向我提问，不要用纯文字提问
- 每轮提问后，根据我的回答总结洞察，再发起下一轮提问
- 至少覆盖以下维度：游戏类型、核心玩法、美术风格、目标平台、技术方案
- 灵活运用 single_select、multi_select、rank_priorities 三种题型
- 3-5 轮提问结束后，输出一份「游戏设计一页纸」

从第一轮开始吧。

1
2
3
4
5

对于这个问题，我们还有哪些没有考虑到的？

使用 AskUserQuestion 工具，像苏格拉底一样帮助我，
无论是技术选型、潜在风险、需求对齐等等任何方向，
因为我是小白我什么都不懂，请帮助我理解。

1
2
3
4
5
6

claude --permission-mode plan
# 进入 Plan Mode 后
> 阅读 /src/auth 目录，了解我们如何处理会话和登录。
> 同时看看我们如何管理用于密钥的环境变量。
> 我想添加 Google OAuth 登录。需要修改哪些文件？
> 会话流程是怎样的？创建一个实施计划。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 会话 A（Plan Mode）
> 分析 @src/auth 目录，制定添加 Google OAuth 的实施计划

# 会话 B（独立会话）
> 审查这个实施计划 [粘贴计划]。
> 指出遗漏的边界情况、潜在的安全问题、和更好的替代方案。

# 会话 A（继续）
> 按你的计划实现 OAuth 流程。
> 为回调处理器编写测试，运行测试套件并修复所有失败。

1
2
3
4
5
6
7
8
9

# gh - GitHub 官方 CLI
brew install gh
gh auth login

# jq - JSON 解析器
brew install jq

# ripgrep - 高速代码搜索
brew install ripgrep

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# skills/fix-issue/SKILL.md
---
name: fix-issue
description: 修复 GitHub Issue 的标准工作流
---

# Fix Issue Workflow

1. 读 issue 描述
2. 在 codebase 里搜索相关代码
3. 写失败测试
4. 实现修复
5. 验证测试通过
6. 提交 PR，关联 issue

1
2

# 调用 skill
> /fix-issue #123

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# agents/code-reviewer.md
---
name: code-reviewer
description: 自动审查 PR 的代码
tools: [Read, Grep, Bash]
---

你是严格的代码审查员。审查 PR 改动，给出：
1. 安全问题
2. 性能问题
3. 与项目风格的一致性

按严重度（Critical / Warning / Suggestion）输出。

1
2

# 主线程委派
> 用 code-reviewer sub-agent 审查 PR #456

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

用户提出需求
    ↓
[Agent 1: 采访模式]  → spec.md
    ↓
[Agent 2: 架构师]     → plan.md
    ↓
[Agent 3: 任务分解]   → tasks.md
    ↓
[Agent 4-N: 实现]     → 代码 + 测试（TDD）
    ↓
[Agent N+1: 审查]     → 优化建议
    ↓
合并 → PR

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

个人开发
├── Claude Code + Claude 4 Opus
├── Cursor + Claude 4 Sonnet（IDE 内）
└── Continue + DeepSeek V3（免费日常）

企业团队
├── Claude Code 团队版（统一计费 + 共享 skills）
├── Cursor Business（企业 SSO）
├── 自建 Qwen2.5-Coder-32B（敏感代码本地化）
└── 规范驱动工作流（spec.md / plan.md / tasks.md）