base

基础技能 — 通用模式

核心原则

复杂性是敌人。每一行代码都是一项负担。我们的目标是构建足够简单的软件，让任何工程师（或 AI）都能在一次会话中理解整个系统。

---

简洁规则

这些限制适用于创建或修改的每个文件。

函数级

• 每个函数最多 20 行 — 如果超过，立即拆分
• 每个函数最多 3 个参数 — 如果超过，使用选项对象或拆分函数
• 最多 2 层嵌套 — 使用提前返回或提取函数来扁平化
• 单一职责 — 每个函数只做一件事
• 优先使用描述性名称，而非注释 — 如果需要注释来解释用途，就重命名

文件级

• 每个文件最多 200 行 — 如果超过，继续之前按职责拆分
• 每个文件最多 10 个函数 — 保持认知负担可控
• 每个文件聚焦一个导出项 — 一个文件应只有一个主要用途

模块级

• 目录嵌套最多 3 层 — 扁平优于嵌套
• 边界清晰 — 每个模块只有一个公共接口
• 禁止循环依赖 — 绝不允许

执行规程

完成任何文件之前：

1. 统计总行数 — 如果 > 200，停止并拆分
2. 统计函数数量 — 如果 > 10，停止并拆分
3. 检查每个函数的长度 — 如果任何函数 > 20 行，停止并拆分
4. 检查参数数量 — 如果任何函数 > 3 个参数，停止并重构

如果开发期间超出限制：

⚠️ FILE SIZE VIOLATION DETECTED

[filename] has [X] lines (limit: 200)

Splitting into:
- [filename-a].ts - [responsibility A]
- [filename-b].ts - [responsibility B]

绝不推迟重构。 立即修复违规，不要留到“以后”。

---

架构模式

函数式核心，命令式外壳

• 使用纯函数处理业务逻辑 — 无副作用，结果确定
• 仅在边界处产生副作用 — 在边缘进行 API 调用、数据库和文件系统操作
• 数据输入，数据输出 — 函数转换数据，而不是改变状态

组合优于继承

• 继承层级不超过 1 层 — 优先使用接口或组合
• 使用小型、可组合的工具 — 用简单的构建复杂的
• 依赖注入 — 传入依赖，不要直接导入

错误处理

• 快速失败，明确报错 — 立即暴露错误
• 不允许静默失败 — 每个错误都要记录或抛出
• 设计 API，使其不可能被误用

---

测试理念

• 业务逻辑达到 100% 覆盖率 — 函数式核心
• 为边界编写集成测试 — API 端点、数据库操作
• 禁止合并未经测试的代码 — 未通过测试时，CI 会阻止合并
• 测试行为，而非实现 — 重构后测试依然有效
• 每项测试都独立运行 — 互不依赖

---

反模式（绝不这样做）

• ❌ 全局状态
• ❌ 魔法数字/字符串 — 使用命名常量
• ❌ 深层嵌套 — 扁平化或提取
• ❌ 过长的参数列表 — 使用对象
• ❌ 用注释解释“做什么” — 代码应能自我说明
• ❌ 死代码 — 删除它，git 会记住
• ❌ 复制粘贴式重复 — 提取为共享函数
• ❌ 上帝对象/文件 — 按职责拆分
• ❌ 循环依赖
• ❌ 过早优化
• ❌ 大型 PR — 只做小而聚焦的更改
• ❌ 将重构与功能混在一起 — 分开提交

---

文档结构

每个项目都必须清晰区分代码文档和项目规格：

project/
├── docs/                      # Code documentation
│   ├── architecture.md        # System design decisions
│   ├── api.md                 # API reference (if applicable)
│   └── setup.md               # Development setup guide
├── _project_specs/            # Project specifications
│   ├── overview.md            # Project vision and goals
│   ├── features/              # Feature specifications
│   │   ├── feature-a.md
│   │   └── feature-b.md
│   ├── todos/                 # Atomic todos tracking
│   │   ├── active.md          # Current sprint/focus
│   │   ├── backlog.md         # Future work
│   │   └── completed.md       # Done items (for reference)
│   ├── session/               # Session state (see session-management.md)
│   │   ├── current-state.md   # Live session state
│   │   ├── decisions.md       # Key decisions log
│   │   ├── code-landmarks.md  # Important code locations
│   │   └── archive/           # Past session summaries
│   └── prompts/               # LLM prompt specifications (if AI-first)
└── CLAUDE.md                  # Claude instructions (references skills)

内容放在哪里

位置	内容
docs/	技术文档、API 参考、设置指南
_project_specs/	业务逻辑、功能、需求、待办事项
_project_specs/session/	会话状态、决策、可恢复上下文
CLAUDE.md	Claude 专属说明和技能参考

---

原子化待办事项

所有工作都以原子化待办事项跟踪，并包含验证和测试标准。

待办事项格式（必需）

## [TODO-001] Short descriptive title

**Status:** pending | in-progress | blocked | done
**Priority:** high | medium | low
**Estimate:** XS | S | M | L | XL

### Description
One paragraph describing what needs to be done.

### Acceptance Criteria
- [ ] Criterion 1 - specific, measurable
- [ ] Criterion 2 - specific, measurable

### Validation
How to verify this is complete:
- Manual: [steps to manually test]
- Automated: [test file/command that validates this]

### Test Cases
| Input | Expected Output | Notes |
|-------|-----------------|-------|
| ... | ... | ... |

### Dependencies
- Depends on: [TODO-xxx] (if any)
- Blocks: [TODO-yyy] (if any)

### TDD Execution Log
| Phase | Command | Result | Timestamp |
|-------|---------|--------|-----------|
| RED | `[test command]` | - | - |
| GREEN | `[test command]` | - | - |
| VALIDATE | `[lint && typecheck && test --coverage]` | - | - |
| COMPLETE | Moved to completed.md | - | - |

Todo 规则

1. 原子性 - 每个 todo 都是一个可完成的工作单元
2. 可测试 - 每个 todo 都有验证标准和测试用例
3. 规模适当 - 如果规模超过“M”，就进一步拆分
4. 独立性 - 尽量减少 todo 之间的依赖
5. 跟踪状态 - 完成后从 active.md 移至 completed.md

Todo 执行工作流（TDD - 强制）

每个 todo 都必须严格遵循以下工作流，不得例外。

┌─────────────────────────────────────────────────────────────┐
│  1. RED: Write Tests First                                  │
│     └─ Create test file(s) based on Test Cases table        │
│     └─ Tests should cover all acceptance criteria           │
│     └─ Run tests → ALL MUST FAIL (proves tests are valid)   │
├─────────────────────────────────────────────────────────────┤
│  2. GREEN: Implement the Feature                            │
│     └─ Write minimum code to make tests pass                │
│     └─ Follow simplicity rules (20 lines/function, etc.)    │
│     └─ Run tests → ALL MUST PASS                            │
├─────────────────────────────────────────────────────────────┤
│  3. VALIDATE: Quality Gates                                 │
│     └─ Run linter (auto-fix if possible)                    │
│     └─ Run type checker (tsc/mypy/pyright)                  │
│     └─ Run full test suite with coverage                    │
│     └─ Verify coverage threshold (≥80%)                     │
├─────────────────────────────────────────────────────────────┤
│  4. PROVE + COMPLETE: Show evidence, then mark done         │
│     └─ Only after ALL validations pass                      │
│     └─ SHOW PROOF — paste the real test/lint/type output    │
│        (pass/fail counts), never just "tests pass"          │
│     └─ UI change? attach a screenshot / visual-diff         │
│     └─ Web user-facing flow? record a demo-video walkthrough │
│     └─ Security-critical change? run a security-audit pass   │
│     └─ Generated content? show the actual artifact          │
│     └─ Move todo to completed.md + checkpoint session state │
└─────────────────────────────────────────────────────────────┘

完成 = 有证据证明，而非口头声称。 只有在回复中提供证据，todo 才算完成：真实的命令输出；任何 UI 更改都需提供截图；任何面向用户的 Web 流程都需提供 demo-video 演示；任何生成内容都需提供实际产物。没有证据 → 未完成。（请参阅 CLAUDE.md 中的“完成定义 — 不可妥协”部分。）

各技术栈的执行命令

Node.js/TypeScript：

# 1. RED - Run tests (expect failures)
npm test -- --grep "todo-description"

# 2. GREEN - Run tests (expect pass)
npm test -- --grep "todo-description"

# 3. VALIDATE - Full quality check
npm run lint && npm run typecheck && npm test -- --coverage

Python：

# 1. RED - Run tests (expect failures)
pytest -k "todo_description" -v

# 2. GREEN - Run tests (expect pass)
pytest -k "todo_description" -v

# 3. VALIDATE - Full quality check
ruff check . && mypy . && pytest --cov --cov-fail-under=80

React/Next.js：

# 1. RED - Run tests (expect failures)
npm test -- --testPathPattern="ComponentName"

# 2. GREEN - Run tests (expect pass)
npm test -- --testPathPattern="ComponentName"

# 3. VALIDATE - Full quality check
npm run lint && npm run typecheck && npm test -- --coverage --watchAll=false

阻止完成的条件

出现以下情况时，绝不能将 todo 标记为已完成：

• ❌ 未先编写测试（跳过 RED 阶段）
• ❌ 测试最初未失败（测试无效）
• ❌ 任何测试失败
• ❌ Linter 存在错误（警告可能可以接受）
• ❌ 类型检查器存在错误
• ❌ 覆盖率低于阈值

如果因失败而受阻：

## [TODO-042] - BLOCKED

**Blocking Reason:** [Lint error in X / Test failure in Y / Coverage at 75%]
**Action Required:** [Specific fix needed]

Bug 修复工作流（TDD - 强制）

用户报告 bug 时，绝不能直接着手修复。

┌─────────────────────────────────────────────────────────────┐
│  1. DIAGNOSE: Identify the Test Gap                         │
│     └─ Run existing tests - do any fail?                    │
│     └─ If tests pass but bug exists → tests are incomplete  │
│     └─ Document: "Test gap: [what was missed]"              │
├─────────────────────────────────────────────────────────────┤
│  2. RED: Write a Failing Test for the Bug                   │
│     └─ Create test that reproduces the exact bug            │
│     └─ Test should FAIL with current code                   │
│     └─ This proves the test catches the bug                 │
├─────────────────────────────────────────────────────────────┤
│  3. GREEN: Fix the Bug                                      │
│     └─ Write minimum code to make the test pass             │
│     └─ Run test → must PASS now                             │
├─────────────────────────────────────────────────────────────┤
│  4. VALIDATE: Full Quality Check                            │
│     └─ Run ALL tests (not just the new one)                 │
│     └─ Run linter and type checker                          │
│     └─ Verify no regression in coverage                     │
└─────────────────────────────────────────────────────────────┘

Bug 报告 Todo 格式

## [BUG-001] Short description of the bug

**Status:** pending
**Priority:** high
**Reported:** [how user reported it / reproduction steps]

### Bug Description
What is happening vs. what should happen.

### Reproduction Steps
1. Step one
2. Step two
3. Observe: [incorrect behavior]
4. Expected: [correct behavior]

### Test Gap Analysis
- Existing test coverage: [list relevant test files]
- Gap identified: [what the tests missed]
- New test needed: [describe the test to add]

### Test Cases for Bug
| Input | Current (Bug) | Expected (Fixed) |
|-------|---------------|------------------|
| ... | ... | ... |

### TDD Execution Log
| Phase | Command | Result | Timestamp |
|-------|---------|--------|-----------|
| DIAGNOSE | `npm test` | All pass (gap!) | - |
| RED | `npm test -- --grep "bug description"` | 1 test failed ✓ | - |
| GREEN | `npm test -- --grep "bug description"` | 1 test passed ✓ | - |
| VALIDATE | `npm run lint && npm run typecheck && npm test -- --coverage` | Pass ✓ | - |

Bug 修复反模式

• ❌ 不写测试就修复 - Bug 很可能会再次出现
• ❌ 修复后才写测试 - 无法证明测试能捕获该 bug
• ❌ 跳过测试差距分析 - 无法找出测试未能捕获问题的原因
• ❌ 只测试修复内容 - 必须运行完整测试套件以检查回归问题

原子 Todo 示例

## [TODO-042] Add email validation to signup form

**Status:** pending
**Priority:** high
**Estimate:** S

### Description
Validate email format on the signup form before submission. Show inline error if invalid.

### Acceptance Criteria
- [ ] Email field shows error for invalid format
- [ ] Error clears when user fixes the email
- [ ] Form cannot submit with invalid email
- [ ] Valid emails pass through without error

### Validation
- Manual: Enter "notanemail" in signup form, verify error appears
- Automated: `npm test -- --grep "email validation"`

### Test Cases
| Input | Expected Output | Notes |
|-------|-----------------|-------|
| [email protected] | Valid, no error | Standard email |
| [email protected] | Valid, no error | Subdomain |
| notanemail | Invalid, show error | No @ symbol |
| user@ | Invalid, show error | No domain |
| @example.com | Invalid, show error | No local part |

### Dependencies
- Depends on: [TODO-041] Signup form component
- Blocks: [TODO-045] Signup flow integration test

### TDD Execution Log
| Phase | Command | Result | Timestamp |
|-------|---------|--------|-----------|
| RED | `npm test -- --grep "email validation"` | 5 tests failed ✓ | - |
| GREEN | `npm test -- --grep "email validation"` | 5 tests passed ✓ | - |
| VALIDATE | `npm run lint && npm run typecheck && npm test -- --coverage` | Pass, 84% coverage ✓ | - |
| COMPLETE | Moved to completed.md | ✓ | - |

---

凭证管理

当项目需要 API 密钥时，务必先向用户索取其集中式访问文件。

工作流

1. Ask: "Do you have an access keys file? (e.g., ~/Documents/Access.txt)"
2. Read and parse the file for known key patterns
3. Validate keys are working
4. Create project .env with found keys
5. Report missing keys and where to get them

要检测的密钥模式

服务	模式	环境变量
OpenAI	sk-proj-*	OPENAI_API_KEY
Claude	sk-ant-*	ANTHROPIC_API_KEY
Render	rnd_*	RENDER_API_KEY
Replicate	r8_*	REPLICATE_API_TOKEN
Reddit	client_id + secret	REDDIT_CLIENT_ID、REDDIT_CLIENT_SECRET

完整的解析逻辑和验证命令请参阅 credentials.md。

---

安全性

每个项目都必须满足以下安全要求。详细模式请参阅 security.md 技能。

基本安全检查

1. 代码中不得包含密钥 - 使用环境变量，绝不提交密钥
2. 将 .env 放入 .gitignore - 始终如此，不得例外
3. 客户端可见的环境变量中不得包含密钥 - 绝不使用 VITE_*、NEXT_PUBLIC_* 存储密钥
4. 验证所有输入 - 在 API 边界使用 Zod/Pydantic
5. 仅使用参数化查询 - 不得通过字符串拼接构造 SQL
6. 正确哈希密码 - 使用 bcrypt，轮数不少于 12
7. 依赖项扫描 - npm audit / safety check 必须通过

必需文件

• 包含密钥模式的 .gitignore
• 包含所有必需变量（不含值）的 .env.example
• 用于提交前验证的 scripts/security-check.sh

CI 中的安全检查

每个 PR 都必须通过：

• 密钥扫描（detect-secrets / trufflehog）
• 依赖项审计（npm audit / safety）
• 静态分析（CodeQL）

---

质量门禁

覆盖率阈值

• 代码覆盖率至少达到 80% - 低于此阈值时 CI 必须失败
• 业务逻辑（core/）应力争达到 100%
• 集成测试应覆盖各个边界

提交前钩子

所有项目都必须配置提交前钩子，运行：

1. Lint 检查（尽可能自动修复）
2. 类型检查
3. 测试（至少运行受影响的测试）

这样可以在问题进入 CI 之前发现它们，节省时间并保持主分支整洁。

---

会话管理

保留上下文以便恢复工作。完整详情请参阅 session-management.md。

核心规则：在自然的停顿点创建检查点

完成任何任务后，请询问：

1. 是否做出了决定？ → 记录到 _project_specs/session/decisions.md
2. 工具调用是否超过 10 次？ → 在 current-state.md 中创建完整检查点
3. 是否完成了重大功能？ → 归档到 session/archive/
4. 否则 → 快速更新 current-state.md

会话开始

1. 阅读 _project_specs/session/current-state.md
2. 检查 _project_specs/todos/active.md
3. 从已记录的“下一步”继续

会话结束

1. 归档当前会话
2. 更新 current-state.md，添加交接说明
3. 确保下一步具体且可执行

---

响应格式

实现功能时（遵循 TDD）：

1. 明确需求（如有歧义）
2. 提出结构——先概述，再编写代码
3. 先编写测试——根据测试用例表（RED 阶段）
4. 运行测试，确认测试失败——证明测试有效
5. 实现最少量的代码，使测试通过（GREEN 阶段）
6. 运行完整验证——lint、类型检查、覆盖率（VALIDATE 阶段）
7. 标记复杂度——接近限制时发出警告
8. 完成后创建检查点——更新会话状态，记录 TDD 执行情况

TDD 不容妥协。 在开始任何实现之前，必须先编写测试并确认测试失败。

发现代码违反这些规则时，请停止并先重构，再继续。

---

自动 TDD 循环（通过 Stop Hook）

.claude/settings.json 中的 Stop Hook 会在每次响应后运行测试。如果测试失败，失败输出会自动反馈给 Claude。无需手动干预。

有关设置详情，请参阅 iterative-development 技能。

工作原理

1. 你要求 Claude 实现某项功能
2. Claude 编写测试和实现
3. Stop Hook 自动运行测试
4. 如果失败：输出会反馈给 Claude，由它修复并重试
5. 如果全部通过：Claude 停止，工作完成

何时触发

任务类型	是否进入 TDD 循环？
新功能	是——每次响应后都会运行测试
Bug 修复	是——先编写失败的测试
重构	是——现有测试会捕获回归问题
简单问题／说明	否——不涉及代码更改
单行修复	否——属于微小更改