core-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Core Workflow Patterns

核心工作流模式

Comprehensive development workflow reference. This loads on-demand for detailed patterns.

Quick links to rules:

~/.claude/rules/

for stack-specific and task-type checklists.

全面的开发工作流参考文档，会按需加载详细模式。

规则快速链接：

~/.claude/rules/

存放特定技术栈和任务类型的检查清单。

Session Protocol

会话协议

Start Checklist

启动检查清单

bash

undefined

bash

undefined

1. Sync with remote (ALWAYS FIRST)

git fetch origin main && git merge origin/main --no-edit

or: git fetch origin master && git merge origin/master --no-edit

2. Get context

git log -3

3. Check for existing work

ls tasks/*.md 2>/dev/null || echo "No active tasks"


**CRITICAL:** Check `<env>` section for today's date. NEVER guess dates.

ls tasks/*.md 2>/dev/null || echo "No active tasks"


**关键注意：** 查看`<env>`部分获取今日日期，绝对不要猜测日期。

End Checklist

结束检查清单

bash

undefined

bash

undefined

1. Verify

npm run test && npm run type-check # or project equivalent

2. Archive completed work

mv tasks/<completed-task>.md .archive/completed-tasks/

3. Commit with comprehensive message

git add . git commit # See Git Conventions below git push origin main


**Stop dev server after testing:** `lsof -ti:PORT | xargs kill` (or Windows equivalent)

---

git add . git commit # See Git Conventions below git push origin main


**测试后停止开发服务器：** `lsof -ti:PORT | xargs kill`（或Windows对应命令）

---

GSD (Get Shit Done) - Multi-Phase Projects

GSD（高效完成任务）- 多阶段项目

For complex features spanning days/weeks, use GSD.

针对耗时数天/数周的复杂功能，使用GSD工作流。

When to Use GSD

何时使用GSD

Complexity	Use GSD?	Workflow
Simple fix (<30 min)	No	Direct execution
Single feature (30min-2hr)	No	Task file + TodoWrite
Multi-phase feature (days)	Yes	GSD workflow
New project/app	Yes	GSD from start

复杂度	是否使用GSD	工作流
简单修复（<30分钟）	否	直接执行
单一功能（30分钟-2小时）	否	任务文件 + TodoWrite
多阶段功能（数天）	是	GSD工作流
新项目/应用	是	从初始阶段就使用GSD

GSD Quick Start

GSD快速开始

bash

/gsd:new-project       # Initialize with brief + config
/gsd:create-roadmap    # Create phases and state tracking
/gsd:plan-phase 1      # Create detailed plan for phase
/gsd:execute-plan <path>  # Execute the plan

bash

/gsd:new-project       # Initialize with brief + config
/gsd:create-roadmap    # Create phases and state tracking
/gsd:plan-phase 1      # Create detailed plan for phase
/gsd:execute-plan <path>  # Execute the plan

GSD Commands Reference

GSD命令参考

Command	Purpose
`/gsd:progress`	Check status, route to next action
`/gsd:resume-work`	Resume from previous session
`/gsd:pause-work`	Create handoff when pausing
`/gsd:plan-phase <n>`	Create detailed phase plan
`/gsd:execute-plan <path>`	Execute a PLAN.md
`/gsd:add-phase <desc>`	Add phase to roadmap
`/gsd:insert-phase <after> <desc>`	Insert urgent work
`/gsd:complete-milestone <ver>`	Archive and tag release
`/gsd:help`	Full command reference

命令	用途
`/gsd:progress`	查看状态，引导至下一步操作
`/gsd:resume-work`	从之前的会话恢复工作
`/gsd:pause-work`	暂停时创建交接文档
`/gsd:plan-phase <n>`	创建详细的阶段计划
`/gsd:execute-plan <path>`	执行PLAN.md文件
`/gsd:add-phase <desc>`	向路线图添加新阶段
`/gsd:insert-phase <after> <desc>`	插入紧急工作
`/gsd:complete-milestone <ver>`	归档并标记版本发布
`/gsd:help`	查看完整命令参考

GSD File Structure

GSD文件结构

.planning/
├── PROJECT.md          # Vision and requirements
├── ROADMAP.md          # Phase breakdown
├── STATE.md            # Project memory (context accumulation)
├── config.json         # Workflow mode (interactive/yolo)
└── phases/
    └── 01-foundation/
        ├── 01-01-PLAN.md
        └── 01-01-SUMMARY.md

.planning/
├── PROJECT.md          # Vision and requirements
├── ROADMAP.md          # Phase breakdown
├── STATE.md            # Project memory (context accumulation)
├── config.json         # Workflow mode (interactive/yolo)
└── phases/
    └── 01-foundation/
        ├── 01-01-PLAN.md
        └── 01-01-SUMMARY.md

Git Conventions

Git约定

Commit Types

提交类型

feat

fix

refactor

perf

test

docs

chore

feat

fix

refactor

perf

test

docs

chore

Commit Message Format

提交消息格式

type: Short summary (50 chars max)

type: Short summary (50 chars max)

What Changed

File X: Added feature Y
File Z: Updated config for A

File X: Added feature Y
File Z: Updated config for A

Why

User requested feature Y
Config A needed update

User requested feature Y
Config A needed update

Testing

All tests passing
Manual verification done

undefined

All tests passing
Manual verification done

undefined

Auto-Commit on Task Completion

任务完成时自动提交

When a task or plan is complete, automatically commit without being asked.

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

Pre-Commit Checks

提交前检查

bash

undefined

bash

undefined

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"

undefined

git remote get-url --push origin | grep -q "no_push" && echo "SKIP: External repo"

undefined

Rules

规则

Condition	Action
User's own repo	Auto-commit + push
External repo ( `no_push` )	Never commit - read-only
Submodule (external)	Never commit - read-only
Uncommitted secrets detected	Block - warn user

条件	操作
用户自有仓库	自动提交并推送
外部仓库（ `no_push` ）	绝对不要提交 - 只读模式
子模块（外部）	绝对不要提交 - 只读模式
检测到未提交的敏感信息	阻止提交 - 向用户发出警告

Security Checklist

安全检查清单

Frontend

前端

Backend

后端

Input validation on all endpoints
Auth guards on protected routes
Parameterized queries (no raw SQL)
Secrets in environment variables

所有端点都进行输入验证
受保护路由添加认证守卫
使用参数化查询（避免原生SQL）
敏感信息存储在环境变量中

Performance Targets

性能目标

Metric	Target
Initial bundle	<100KB gzipped
Page load	<1s
Interaction latency	<100ms
Lighthouse Performance	95+
Accessibility	WCAG AA minimum

指标	目标值
初始包大小	压缩后<100KB
页面加载时间	<1秒
交互延迟	<100毫秒
Lighthouse性能评分	95+
可访问性	至少符合WCAG AA标准

Accessibility (WCAG AA)

可访问性（WCAG AA标准）

Testing Strategy

测试策略

Type	Location	When
Unit	`src/**/__tests__/`	Every function
Component	Same	Every component
Integration	`tests/integration/`	Critical paths
E2E	`tests/e2e/`	Before release

Before committing:

npm run test && npm run type-check

类型	位置	执行时机
单元测试	`src/**/__tests__/`	每个函数开发完成后
组件测试	同一目录	每个组件开发完成后
集成测试	`tests/integration/`	关键路径验证
端到端测试	`tests/e2e/`	发布前

提交前必须执行：

npm run test && npm run type-check

Thinking Frameworks

思维框架

Use structured decision-making for complex choices:

Decision Type	Framework
Long-term implications	`/consider:10-10-10`
Root cause analysis	`/consider:5-whys`
Prioritization	`/consider:eisenhower-matrix`
Innovation	`/consider:first-principles`
Risk identification	`/consider:inversion`
Simplification	`/consider:occams-razor`
Focus	`/consider:one-thing`
Tradeoffs	`/consider:opportunity-cost`
Optimization	`/consider:pareto`
Consequences	`/consider:second-order`

针对复杂决策使用结构化决策方法：

决策类型	框架
长期影响	`/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`

Debugging Protocol

调试协议

Standard Issues

常规问题

Reproduce the issue
Read relevant code
Identify root cause
Fix + add test
Verify fix

复现问题
阅读相关代码
确定根本原因
修复并添加测试
验证修复效果

Intermittent/Complex Issues

间歇性/复杂问题

Use

debug-like-expert

skill for systematic approach.

使用

debug-like-expert

技能进行系统化排查。

Build vs Buy Philosophy

自研vs外购哲学

We build features. We use utilities.

Build: All feature logic, business rules, UI/UX, data models
Use: Low-level abstractions (D3, Recharts, Lexical, Konva)
Criterion: We own the feature, library handles complexity

我们自研功能逻辑，使用现成工具。

自研： 所有功能逻辑、业务规则、UI/UX、数据模型
使用： 底层抽象库（D3、Recharts、Lexical、Konva）
判断标准： 我们掌控功能核心，库处理底层复杂度

License Requirements

许可证要求

Must use: MIT, Apache 2.0, BSD
Never use: GPL, AGPL (blocks commercialization)

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

Communication Standards

沟通标准

Progress Updates

进度更新

Give high-level updates, not spam:

✅ Added authentication middleware (3 files)
✅ Updated user store with new fields
⏳ Testing login flow...

提供高层级更新，避免冗余信息：

✅ 新增认证中间件（3个文件）
✅ 更新用户存储新增字段
⏳ 正在测试登录流程...

When to Ask

何时询问用户

Use

AskUserQuestion

when:

Requirements are ambiguous
Multiple valid architectures exist
Scope might expand
Design decisions need validation

当出现以下情况时使用

AskUserQuestion

：

需求不明确
存在多种可行架构
范围可能扩大
设计决策需要验证

Directness Protocol

直接沟通原则

Logic over feelings
Correctness over validation
Direct feedback over diplomacy
Best solution over agreement

逻辑优先于情绪
正确性优先于认可
直接反馈优先于委婉
最优方案优先于共识

Context Hygiene

上下文管理

Reduce Token Usage

减少Token消耗

Short, high-signal summaries over long logs
Don't
```
@
```
-embed large docs by default
Reference paths + when to read them
Use
```
/clear
```
after completing work units

使用简洁、高信息量的摘要而非冗长日志
默认不要
```
@
```
嵌入大型文档
引用文件路径及阅读时机
完成工作单元后使用
```
/clear
```
命令

Delegation Patterns

委托模式

Situation	Action
Context >100k tokens	Create prompt → delegate to fresh context
Moderate complexity	`/create-prompt` → `/run-prompt`
Multi-stage features	`/create-meta-prompt`
Approaching limits	`/whats-next` for handoff document

场景	操作
上下文超过100k Token	创建提示词 → 委托给新的上下文环境
中等复杂度	`/create-prompt` → `/run-prompt`
多阶段功能	`/create-meta-prompt`
即将达到Token限制	使用 `/whats-next` 生成交接文档

Quick Reference

快速参考

Common Commands

常用命令

bash

npm run dev          # Start dev server
npm run build        # Production build
npm run test         # Run tests
npm run type-check   # TypeScript check

bash

npm run dev          # Start dev server
npm run build        # Production build
npm run test         # Run tests
npm run type-check   # TypeScript check

File Naming

文件命名规范

Type	Convention	Example
Components	PascalCase	`UserCard.tsx`
Hooks	use prefix	`useAuth.ts`
Utilities	camelCase	`utils.ts`
Tests	.test.ts	`utils.test.ts`

类型	命名规则	示例
组件	PascalCase	`UserCard.tsx`
Hooks	use前缀	`useAuth.ts`
工具函数	camelCase	`utils.ts`
测试文件	.test.ts后缀	`utils.test.ts`

Resources

资源

Official

官方资源

Community

社区资源

另请参阅

```
~/.claude/rules/checklists/
```
- Task-type specific checklists
```
~/.claude/rules/stacks/
```
- Stack-specific patterns
```
~/.claude/rules/tooling/
```
- Tool configuration guides
```
~/.claude/skills/MASTER_INDEX.md
```
- Full skills catalog
```
~/.claude/agents/README.md
```
- Agents directory

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