name: base description: Universal coding patterns, constraints, TDD workflow, atomic todos
基础技能 - 通用编程模式
核心原则
复杂性是敌人。每一行代码都是负债。目标是软件足够简单，任何工程师（或AI）都能在一个会话中理解整个系统。
简单性规则（严格执行）
重要：这些限制是不可协商的。Claude 必须检查并强制执行每个创建或修改的文件的这些限制。
函数级别
- 每函数最多20行 - 如果更长，请立即分解
- 每函数最多3个参数 - 如果更多，请使用选项对象或分解
- 最大嵌套层次2级 - 通过早期返回或提取函数来展平
- 单一职责 - 每个函数只做一件事
- 描述性名称优于注释 - 如果需要注释来解释，重命名它
文件级别
- 每文件最多200行 - 如果更长，请在继续之前按职责拆分
- 每文件最多10个函数 - 保持认知负荷可管理
- 每文件一个导出焦点 - 文件应该有一个主要目的
模块级别
- 目录嵌套最多3级 - 扁平比嵌套更好
- 清晰的界限 - 每个模块有一个单一的公共接口
- 无循环依赖 - 永远
执行协议
在完成任何文件之前：
- 计算总行数 - 如果超过200行，停止并拆分
- 计算函数数量 - 如果超过10个，停止并拆分
- 检查每个函数的长度 - 如果超过20行，停止并分解
- 检查参数数量 - 如果超过3个，停止并重构
如果在开发过程中超出限制：
⚠️ 文件大小违规检测
[filename]有[X]行（限制：200）
拆分为：
- [filename-a].ts - [responsibility A]
- [filename-b].ts - [responsibility B]
永远不要推迟重构。 立即修复违规行为，而不是“稍后”。
架构模式
函数核心，命令外壳
- 纯函数用于业务逻辑 - 无副作用，确定性
- 仅在边界处有副作用 - API调用，数据库，文件系统在边缘
- 数据输入，数据输出 - 函数转换数据，它们不改变状态
组合优于继承
- 继承不超过1级 - 优先使用接口/组合
- 小型，可组合的实用程序 - 从简单构建复杂
- 依赖注入 - 传递依赖，不直接导入
错误处理
- 快速失败，大声失败 - 错误立即浮出水面
- 无静默失败 - 每个错误都被记录或抛出
- 设计API使得误用变得不可能
测试哲学
- 业务逻辑100%覆盖 - 函数核心
- 边界的集成测试 - API端点，数据库操作
- 无未测试代码合并 - CI阻止未通过测试的合并
- 测试行为，非实现 - 测试在重构后仍然存活
- 每个测试独立运行 - 无相互依赖
反模式（永不这样做）
- ❌ 全局状态
- ❌ 魔术数字/字符串 - 使用命名常量
- ❌ 深层嵌套 - 展平或提取
- ❌ 长参数列表 - 使用对象
- ❌ 解释“什么”的注释 - 代码应该是自文档化的
- ❌ 死代码 - 删除它，git记得
- ❌ 复制粘贴重复 - 提取到共享函数
- ❌ 上帝对象/文件 - 按职责拆分
- ❌ 循环依赖
- ❌ 过早优化
- ❌ 大型PR - 仅限小型，专注的更改
- ❌ 混合重构与功能 - 分开提交
文档结构
每个项目必须在代码文档和项目规范之间有明确的分离：
project/
├── docs/ # 代码文档
│ ├── architecture.md # 系统设计决策
│ ├── api.md # API参考（如适用）
│ └── setup.md # 开发设置指南
├── _project_specs/ # 项目规范
│ ├── overview.md # 项目愿景和目标
│ ├── features/ # 功能规范
│ │ ├── feature-a.md
│ │ └── feature-b.md
│ ├── todos/ # 原子待办事项跟踪
│ │ ├── active.md # 当前冲刺/焦点
│ │ ├── backlog.md # 未来工作
│ │ └── completed.md # 完成项（供参考）
│ ├── session/ # 会话状态（见session-management.md）
│ │ ├── current-state.md # 实时会话状态
│ │ ├── decisions.md # 关键决策日志
│ │ ├── code-landmarks.md # 重要代码位置
│ │ └── archive/ # 过去会话摘要
│ └── prompts/ # LLM提示规范（如果AI优先）
└── CLAUDE.md # Claude指令（引用技能）
什么放在哪里
| 位置 | 内容 |
|---|---|
docs/ |
技术文档，API参考，设置指南 |
_project_specs/ |
业务逻辑，功能，需求，待办事项 |
_project_specs/session/ |
会话状态，决策，上下文用于可恢复性 |
CLAUDE.md |
Claude特定指令和技能引用 |
原子待办事项
所有工作都作为原子待办事项进行跟踪，具有验证和测试标准。
待办事项格式（必需）
## [TODO-001] 简短描述标题
**状态：** 待定 | 进行中 | 阻塞 | 完成
**优先级：** 高 | 中 | 低
**估计：** XS | S | M | L | XL
### 描述
一段描述需要完成的工作。
### 验收标准
- [ ] 标准1 - 具体，可衡量
- [ ] 标准2 - 具体，可衡量
### 验证
如何验证这项工作已完成：
- 手动：[手动测试步骤]
- 自动：[测试文件/命令，验证这一点]
### 测试用例
| 输入 | 预期输出 | 注释 |
|-------|-----------------|-------|
| ... | ... | ... |
### 依赖项
- 依赖于：[TODO-xxx]（如果有）
- 阻塞：[TODO-yyy]（如果有）
### TDD执行日志
| 阶段 | 命令 | 结果 | 时间戳 |
|-------|---------|--------|-----------|
| RED | `[test command]` | - | - |
| GREEN | `[test command]` | - | - |
| VALIDATE | `[lint && typecheck && test --coverage]` | - | - |
| COMPLETE | 移动到completed.md | - | - |
待办事项规则
- 原子 - 每个待办事项是一个单一的，可完成的工作单元
- 可测试 - 每个待办事项都有验证标准和测试用例
- 大小 - 如果大于"M"，请进一步拆分
- 独立 - 最小化待办事项之间的依赖
- 跟踪 - 在完成时在active.md → completed.md之间移动
待办事项执行工作流程（TDD - 强制）
每个待办事项必须严格遵循这个确切的工作流程。没有例外。
┌─────────────────────────────────────────────────────────────┐
│ 1. RED: 首先编写测试 │
│ └─ 根据测试用例表创建测试文件 │
│ └─ 测试应涵盖所有验收标准 │
│ └─ 运行测试 → 所有必须失败（证明测试有效） │
├─────────────────────────────────────────────────────────────┤
│ 2. GREEN: 实现功能 │
│ └─ 编写最少的代码以使测试通过 │
│ └─ 遵循简单性规则（每函数20行等） │
│ └─ 运行测试 → 所有必须通过 │
├─────────────────────────────────────────────────────────────┤
│ 3. VALIDATE: 质量门 │
│ └─ 运行linter（如果可能则自动修复） │
│ └─ 运行类型检查器（tsc/mypy/pyright） │
│ └─ 运行完整的测试套件与覆盖度 │
│ └─ 验证覆盖度阈值（≥80%） │
├─────────────────────────────────────────────────────────────┤
│ 4. COMPLETE: 标记完成 │
│ └─ 只有在所有验证通过后才能完成 │
│ └─ 将待办事项移动到completed.md │
│ └─ 检查点会话状态 │
└─────────────────────────────────────────────────────────────┘
按堆栈执行命令
Node.js/TypeScript:
# 1. RED - 运行测试（预期失败）
npm test -- --grep "todo-description"
# 2. GREEN - 运行测试（预期通过）
npm test -- --grep "todo-description"
# 3. VALIDATE - 完整质量检查
npm run lint && npm run typecheck && npm test -- --coverage
Python:
# 1. RED - 运行测试（预期失败）
pytest -k "todo_description" -v
# 2. GREEN - 运行测试（预期通过）
pytest -k "todo_description" -v
# 3. VALIDATE - 完整质量检查
ruff check . && mypy . && pytest --cov --cov-fail-under=80
React/Next.js:
# 1. RED - 运行测试（预期失败）
npm test -- --testPathPattern="ComponentName"
# 2. GREEN - 运行测试（预期通过）
npm test -- --testPathPattern="ComponentName"
# 3. VALIDATE - 完整质量检查
npm run lint && npm run typecheck && npm test -- --coverage --watchAll=false
阻塞条件
如果因为失败而标记待办事项为完成：
- ❌ 测试没有首先编写（跳过RED阶段）
- ❌ 测试最初没有失败（无效测试）
- ❌ 任何测试失败
- ❌ Linter有错误（警告可能是可以接受的）
- ❌ 类型检查器有错误
- ❌ 覆盖度低于阈值
如果因失败而阻塞：
## [TODO-042] - BLOCKED
**阻塞原因：** [X中的Lint错误 / Y中的测试失败 / 覆盖度为75%]
**所需行动：** [需要的具体修复]
错误修复工作流程（TDD - 强制）
当用户报告错误时，永远不要直接跳到修复它。
┌─────────────────────────────────────────────────────────────┐
│ 1. DIAGNOSE: 确定测试缺口 │
│ └─ 运行现有测试 - 有失败吗？ │
│ └─ 如果测试通过但错误存在 → 测试不完整 │
│ └─ 文档："测试缺口：[错过什么]" │
├─────────────────────────────────────────────────────────────┤
│ 2. RED: 为错误编写失败测试 │
│ └─ 创建测试以重现确切的错误 │
│ └─ 测试应该用当前代码失败 │
│ └─ 这证明了测试捕捉到了错误 │
├─────────────────────────────────────────────────────────────┤
│ 3. GREEN: 修复错误 │
│ └─ 编写最少的代码以使测试通过 │
│ └─ 运行测试 → 现在必须通过 │
├─────────────────────────────────────────────────────────────┤
│ 4. VALIDATE: 完整质量检查 │
│ └─ 运行所有测试（不仅仅是新的） │
│ └─ 运行linter和类型检查器 │
│ └─ 验证没有回归覆盖度 │
└─────────────────────────────────────────────────────────────┘
错误报告待办事项格式
## [BUG-001] 错误简短描述
**状态：** 待定
**优先级：** 高
**报告：** [用户如何报告它/重现步骤]
### 错误描述
发生了什么与应该发生的事情。
### 重现步骤
1. 第一步
2. 第二步
3. 观察：[错误行为]
4. 预期：[正确行为]
### 测试缺口分析
- 现有测试覆盖范围：[列出相关测试文件]
- 识别的缺口：[测试错过了什么]
- 需要的新测试：[描述要添加的测试]
### 错误测试用例
| 输入 | 当前（错误） | 预期（修复） |
|-------|---------------|------------------|
| ... | ... | ... |
### TDD执行日志
| 阶段 | 命令 | 结果 | 时间戳 |
|-------|---------|--------|-----------|
| DIAGNOSE | `npm test` | 所有通过（缺口！） | - |
| RED | `npm test -- --grep "bug description"` | 1测试失败 ✓ | - |
| GREEN | `npm test -- --grep "bug description"` | 1测试通过 ✓ | - |
| VALIDATE | `npm run lint && npm run typecheck && npm test -- --coverage` | 通过 ✓ | - |
错误修复反模式
- ❌ 无测试修复 - 错误可能会再次出现
- ❌ 修复后编写测试 - 不能证明测试捕捉到了错误
- ❌ 跳过测试缺口分析 - 错过了为什么测试没有捕捉到
- ❌ 仅测试修复 - 必须运行完整的测试套件以防止回归
示例原子待办事项
## [TODO-042] 在注册表单中添加电子邮件验证
**状态：** 待定
**优先级：** 高
**估计：** S
### 描述
在提交前在注册表单上验证电子邮件格式。如果无效，请显示内联错误。
### 验收标准
- [ ] 电子邮件字段显示无效格式错误
- [ ] 用户修复电子邮件时错误清除
- [ ] 表单不能用无效的电子邮件提交
- [ ] 有效电子邮件无错误通过
### 验证
- 手动：在注册表单中输入"notanemail"，验证错误是否出现
- 自动：`npm test -- --grep "email validation"`
### 测试用例
| 输入 | 预期输出 | 注释 |
|-------|-----------------|-------|
| user@example.com | 有效，无错误 | 标准电子邮件 |
| user@sub.example.com | 有效，无错误 | 子域 |
| notanemail | 无效，显示错误 | 没有@符号 |
| user@ | 无效，显示错误 | 没有域 |
| @example.com | 无效，显示错误 | 没有本地部分 |
### 依赖项
- 依赖于：[TODO-041] 注册表单组件
- 阻塞：[TODO-045] 注册流程集成测试
### TDD执行日志
| 阶段 | 命令 | 结果 | 时间戳 |
|-------|---------|--------|-----------|
| RED | `npm test -- --grep "email validation"` | 5测试失败 ✓ | - |
| GREEN | `npm test -- --grep "email validation"` | 5测试通过 ✓ | - |
| VALIDATE | `npm run lint && npm run typecheck && npm test -- --coverage` | 通过，84%覆盖 ✓ | - |
| COMPLETE | 移动到completed.md | ✓ | - |
凭据管理（不可协商）
当项目需要API密钥时，始终首先询问用户的集中访问文件。
工作流程
1. 询问："您有访问密钥文件吗？（例如，~/Documents/Access.txt）"
2. 读取并解析文件以获取已知的密钥模式
3. 验证密钥是否有效
4. 使用找到的密钥创建项目.env
5. 报告缺少的密钥以及如何获得它们
要检测的密钥模式
| 服务 | 模式 | 环境变量 |
|---|---|---|
| OpenAI | sk-proj-* |
OPENAI_API_KEY |
| Claude | sk-ant-* |
ANTHROPIC_API_KEY |
| Render | rnd_* |
RENDER_API_KEY |
| Replicate | r8_* |
REPLICATE_API_TOKEN |
| 客户端ID + 密钥 | REDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET |
查看credentials.md了解完整的解析逻辑和验证命令。
安全（不可协商）
每个项目都必须满足这些安全要求。查看security.md技能了解详细的模式。
基本安全检查
- 代码中无秘密 - 使用环境变量，永不提交秘密
.env在.gitignore中 - 总是，无例外- 客户端暴露的环境变量中无秘密 - 永远不要使用
VITE_*,NEXT_PUBLIC_*用于秘密 - 验证所有输入 - 在API边界使用Zod/Pydantic
- 仅参数化查询 - 不要为SQL进行字符串拼接
- 正确哈希密码 - 使用12+轮的bcrypt
- 依赖项扫描 - npm审计/安全检查必须通过
必需文件
.gitignore带有秘密模式.env.example带有所有必需变量（无值）scripts/security-check.sh用于预提交验证
CI中的安全
每个PR必须通过：
- 秘密扫描（detect-secrets / trufflehog）
- 依赖审计（npm审计/安全）
- 静态分析（CodeQL）
质量门（不可协商）
覆盖度阈值
- 最低80%代码覆盖度 - CI必须在此以下失败
- 业务逻辑（core/）应瞄准100%
- 集成测试覆盖边界
预提交钩子
所有项目必须有预提交钩子，运行：
- 代码检查（如果可能则自动修复）
- 类型检查
- 测试（至少，受影响的测试）
这在问题进入CI之前捕捉问题，节省时间并保持主线干净。
会话管理（不可协商）
保持上下文以恢复。查看session-management.md了解详细信息。
核心规则：在自然断点处检查点
完成任何任务后，询问：
- 决策做出？ → 记录到
_project_specs/session/decisions.md - >10工具调用？ → 完整检查点到
current-state.md - 主要功能完成？ → 归档到
session/archive/ - 否则 → 更新到
current-state.md
会话开始
- 读取
_project_specs/session/current-state.md - 检查
_project_specs/todos/active.md - 从记录的"下一步"继续
会话结束
- 归档当前会话
- 更新
current-state.md带有交接注释 - 确保下一步是具体且可操作的
响应格式
当实现功能（遵循TDD）时：
- 澄清要求 如果含糊不清
- 提出结构 - 在代码之前概述
- 首先编写测试 - 基于测试用例表（RED阶段）
- 运行测试以验证它们失败 - 证明测试有效
- 实现最少代码 以使测试通过（GREEN阶段）
- 运行完整验证 - 代码检查，类型检查，覆盖度（VALIDATE阶段）
- 标记复杂性 - 如果接近限制则警告
- 完成后检查点 - 更新会话状态，记录TDD执行
TDD是不可协商的。 在任何实现开始之前，测试必须存在并且失败。
当您注意到违反这些规则的代码时，停止并重构 然后再继续。
自动迭代模式（Ralph Wiggum）
对于任何非平凡任务，Claude必须自动使用迭代TDD循环。
何时自动调用Ralph循环
| 任务类型 | 行动 |
|---|---|
| 新功能（任何大小） | /ralph-loop带有TDD模板 |
| 错误修复 | /ralph-loop带有错误修复模板 |
| 重构 | /ralph-loop带有重构模板 |
| API开发 | /ralph-loop带有API模板 |
| 简单问题/解释 | 正常响应（无循环） |
| 一行修复（错别字等） | 正常响应（无循环） |
自动转换用户请求
当用户说：
- “添加电子邮件验证”
- “修复登录错误”
- “为待办事项构建REST API”
- “重构认证模块”
Claude必须自动：
- 从请求中提取要求
- 定义完成标准（测试通过，代码检查干净等）
- 作为Ralph提示结构化带有TDD工作流程
- 调用
/ralph-loop带有适当的--max-iterations和--completion-promise
自动转换示例
用户说：
“添加一个忘记密码功能”
Claude自动调用：
/ralph-loop "
## 任务：添加忘记密码功能
### 要求（从用户请求中提取）
- 用户可以通过电子邮件请求密码重置
- 重置链接发送到注册的电子邮件
- 链接在24小时后过期
- 用户可以通过链接设置新密码
### TDD工作流程
1. 为每个要求编写失败的测试
2. 验证测试失败（RED）
3. 实现功能
4. 验证测试通过（GREEN）
5. 运行代码检查+类型检查
6. 如果失败则重复
### 完成标准
- [ ] 所有测试通过
- [ ] 覆盖度≥80%
- [ ] 代码检查干净
- [ ] 安全审查（URL参数中无令牌等）
### 退出条件
<promise>FORGOT PASSWORD COMPLETE</promise>
" --completion-promise "FORGOT PASSWORD COMPLETE" --max-iterations 25
默认设置
| 设置 | 默认 | 理由 |
|---|---|---|
--max-iterations |
20-30 | 安全网，根据复杂性调整 |
--completion-promise |
总是设置 | 基于任务（例如，“TESTS PASSING”） |
| TDD工作流程 | 总是包括 | 不可协商 |
选择退出
用户可以通过说：
- “只是解释…”（仅解释）
- “快速修复…”（一行修复）
- “不要循环…”（明确选择退出）
- “帮助我理解…”（学习/讨论） 退出自动Ralph循环