core-workflow

核心工作流模式

全面的开发工作流参考。需要详细模式时按需加载。

规则快速链接： ~/.claude/rules/，用于特定技术栈和任务类型的检查清单。

---

会话协议

开始检查清单

# 1. Sync first: default branch from origin/HEAD, fetch + prune, fast-forward
git fetch --prune origin && git merge --ff-only "$(git symbolic-ref --short refs/remotes/origin/HEAD)"

# 2. Get context
git log -3

# 3. Check for existing work
ls tasks/*.md 2>/dev/null || echo "No active tasks"

从环境上下文中获取今天的日期，而不要自行推断。

结束检查清单

# 1. Verify by review: re-read the request and the whole diff (no test/type-check ladder)

# 2. Archive completed work
mv tasks/<completed-task>.md .archive/completed-tasks/

# 3. Commit with comprehensive message
git add -A  # all pending changes, any session's
git commit  # See Git Conventions below
git push    # or the configured push runner, when one is defined; never force

停止你启动的所有开发服务器： lsof -ti:PORT | xargs kill（或 Windows 上的等效命令）

---

工作量评估

复杂度	工作流
简单修复（<30 分钟）	直接执行
单项功能（30 分钟至 2 小时）	任务文件 + TodoWrite
多阶段功能（数天）	规划模式，然后在 tasks/ 中为每个阶段创建一个任务文件
新项目/应用	/init-project，然后为第一阶段启用规划模式

---

Git 约定

提交类型

feat | fix | refactor | perf | test | docs | chore

提交信息格式

type: Short summary (50 chars max)

## What Changed
- File X: Added feature Y
- File Z: Updated config for A

## Why
- User requested feature Y
- Config A needed update

## Verification
- Diff reviewed against the request, callers, and edge cases

任务完成时自动提交

任务或计划完成时，无需等待询问，自动提交。

提交前检查

# 1. Check this is a user-owned repo (not external)
git remote get-url origin | grep -q "travisjneuman" && echo "OK: User repo"

# 2. Check push is not blocked
git remote get-url --push origin | grep -q "no_push" && echo "SKIP: External repo"

规则

条件	操作
用户自己的仓库	自动提交 + 推送
外部仓库（no_push）	绝不提交 - 只读
子模块（外部）	绝不提交 - 只读
检测到未提交的密钥	阻止 - 警告用户

---

安全检查清单

前端

• 使用 textContent，而非 innerHTML
• 外部数据使用 unknown 类型
• 不暴露 API 密钥
• 外部请求使用 HTTPS
• 清理输入内容

后端

• 验证所有端点的输入
• 为受保护的路由添加身份验证保护
• 使用参数化查询（不使用原始 SQL）
• 将密钥存储在环境变量中

---

性能目标

指标	目标
初始包	<100KB（gzip 压缩后）
页面加载	<1s
交互延迟	<100ms
Lighthouse 性能	95+
无障碍性	至少达到 WCAG AA

---

无障碍性（WCAG AA）

• 使用语义化 HTML 结构
• 为有意义的图片添加替代文本
• 支持键盘导航（Tab、Enter、Escape）
• 焦点指示器清晰可见
• 色彩对比度 >= 4.5:1
• 为交互元素添加 ARIA 标签
• 触控目标 >= 44x44px

---

思维框架

面对复杂选择时，使用结构化决策方法：

决策类型	框架
长期影响	/consider:10-10-10
根因分析	/consider:5-whys
优先级排序	/consider:eisenhower-matrix
创新	/consider:first-principles
风险识别	/consider:inversion
简化	/consider:occams-razor
专注	/consider:one-thing
权衡	/consider:opportunity-cost
优化	/consider:pareto
后果	/consider:second-order

---

调试协议

常见问题

1. 重现问题
2. 阅读相关代码
3. 找出根本原因
4. 修复根本原因
5. 通过审查差异和修复已产生的输出进行验证

间歇性/复杂问题

使用 debug-systematic 技能进行系统化处理。

---

自行构建与购买理念

我们构建功能，使用实用工具。

• 构建： 所有功能逻辑、业务规则、UI/UX、数据模型
• 使用： 底层抽象（D3、Recharts、Lexical、Konva）
• 标准： 功能归我们所有，库负责处理复杂性

许可证要求

• 必须使用： MIT、Apache 2.0、BSD
• 绝不使用： GPL、AGPL（会阻碍商业化）

---

沟通规范

进度更新

提供高层级进度更新，不要刷屏：

“已添加身份验证中间件（3 个文件），并更新了用户存储中的新字段；现在正在检查登录流程。”

何时提问

仅在以下情况使用 AskUserQuestion：

• 缺少关键选择，且会影响结果
• 指令相互冲突，且无法通过优先级确定取舍
• 无法准确确定破坏性操作或外部目标
• 该步骤需要请求中未授予的权限

否则，选择合理的方案并继续，同时说明假设。

直接沟通原则

• 重逻辑，不重感受
• 正确性优于认可
• 直接反馈优于委婉表达
• 选择最佳方案，不盲目附和

---

上下文管理

减少令牌用量

• 使用简短、高信息量的摘要，避免冗长日志
• 默认不要用 @ 嵌入大型文档
• 提供路径，并说明何时阅读
• 完成工作单元后使用 /clear

委派模式

情况	操作
上下文 >100k 个令牌	创建提示词 → 委派至全新上下文
中等复杂度	/create-prompt → /run-prompt
多阶段功能	/create-meta-prompt
接近限制	使用 /whats-next 创建交接文档

---

快速参考

常用命令

npm run dev          # Start dev server
npm run build        # Production build
npm run test         # Run tests (only when the user asks)
npm run type-check   # TypeScript check (only when the user asks)

文件命名

类型	约定	示例
组件	PascalCase	UserCard.tsx
Hook	use 前缀	useAuth.ts
实用工具	camelCase	utils.ts
测试	.test.ts	utils.test.ts

---

资源

官方资源

• Claude Code 文档
• Anthropic 最佳实践

社区资源

• awesome-claude-code
• awesome-claude-md

---

另请参阅

• ~/.claude/docs/reference/checklists/ - 特定任务类型的检查清单
• ~/.claude/docs/reference/stacks/ - 特定技术栈的模式
• ~/.claude/docs/reference/tooling/ - 工具配置指南
• ~/.claude/skills/MASTER_INDEX.md - 完整技能目录
• ~/.claude/agents/README.md - Agent 目录