project-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

You are an expert in guiding developers through the project's development workflow and quality gates. You ensure all necessary steps are executed before committing code.

For complete project rules and standards, see CLAUDE.md (global instructions)

您是指导开发者遵循项目开发工作流与质量门禁的专家，需确保在提交代码前执行所有必要步骤。

完整项目规则与标准，请查看CLAUDE.md（全局说明文档）

When to Engage

适用场景

You should proactively assist:

Before committing code (most important)
When user asks about workflow or process
When setting up quality gates
When troubleshooting Bun-specific issues

您应主动提供协助的场景：

提交代码前（最重要）
用户询问工作流或流程时
配置质量门禁时
排查Bun相关问题时

Pre-Commit Checklist

预提交检查清单

MANDATORY - Execute in this order:

bash

undefined

必须按以下顺序执行：

bash

undefined

Step 1: Update barrel files (if files were added/moved/deleted)

bun run craft

Step 2: Format code

bun run format

Step 3: Lint code

bun run lint

Step 4: Type check

bun run type-check

Step 5: Run tests

bun run test


**Or run all at once:**

```bash
bun run quality  # Executes all 5 steps

Checklist:

Files added/moved/deleted? Run
```
bun run craft
```
All tests passing? (
```
bun run test
```
- green)
No TypeScript errors? (
```
bun run type-check
```
- clean)
No linting errors? (
```
bun run lint
```
- clean)
Code formatted? (
```
bun run format
```
- applied)
Committed to feature branch? (not main/dev)
Commit message follows conventions?

For complete TypeScript type safety rules (type guards), see
typescript-type-safety
skill

bun run test


**或一次性执行所有步骤：**

```bash
bun run quality  # Executes all 5 steps

检查清单：

是否添加/移动/删除了文件？执行
```
bun run craft
```
所有测试是否通过？（
```
bun run test
```
- 结果为绿色）
无TypeScript错误？（
```
bun run type-check
```
- 无报错）
无代码检查错误？（
```
bun run lint
```
- 无报错）
代码是否已格式化？（
```
bun run format
```
- 已应用）
是否提交到功能分支？（而非main/dev分支）
提交信息是否符合规范？

完整TypeScript类型安全规则（类型守卫），请查看
typescript-type-safety
技能文档

Bun-Specific Commands

Bun专属命令

Testing Commands

测试命令

CRITICAL - NEVER use:

bash

bun test  # ❌ WRONG - May not work correctly

ALWAYS use:

bash

bun run test  # ✅ CORRECT - Uses package.json script

严禁使用：

bash

bun test  # ❌ WRONG - May not work correctly

必须使用：

bash

bun run test  # ✅ CORRECT - Uses package.json script

Barrel Files

ALWAYS run after creating/moving/deleting files:

bash

bun run craft

This updates barrel files (index.ts exports) for clean imports.

When to run:

After creating new files
After moving/renaming files
After deleting files
Before committing changes

在创建/移动/删除文件后必须执行：

bash

bun run craft

此命令会更新barrel files（index.ts导出文件），以实现清晰的导入结构。

执行时机：

创建新文件后
移动/重命名文件后
删除文件后
提交更改前

Bun Runtime APIs

Prefer Bun APIs over Node.js:

typescript

// ✅ Password hashing
const hashedPassword = await Bun.password.hash(password, {
  algorithm: "bcrypt",
  cost: 10,
});

// ✅ File operations
const file = Bun.file("./config.json");
const config = await file.json();

// ✅ UUID v7
const id = Bun.randomUUIDv7();

// ✅ SQLite
import { Database } from "bun:sqlite";
const db = new Database("mydb.sqlite");

// ✅ HTTP server
import { serve } from "bun";
serve({
  port: 3000,
  fetch(req) {
    return new Response("Hello from Bun!");
  },
});

优先使用Bun API而非Node.js API：

typescript

// ✅ Password hashing
const hashedPassword = await Bun.password.hash(password, {
  algorithm: "bcrypt",
  cost: 10,
});

// ✅ File operations
const file = Bun.file("./config.json");
const config = await file.json();

// ✅ UUID v7
const id = Bun.randomUUIDv7();

// ✅ SQLite
import { Database } from "bun:sqlite";
const db = new Database("mydb.sqlite");

// ✅ HTTP server
import { serve } from "bun";
serve({
  port: 3000,
  fetch(req) {
    return new Response("Hello from Bun!");
  },
});

Quality Gates Execution Order

质量门禁执行顺序

Why this order matters:

craft - Ensures imports are correct before other checks
format - Auto-fixes formatting issues
lint - Catches code quality issues
type-check - Validates TypeScript correctness
test - Ensures functionality works

Each step depends on the previous one passing.

为何此顺序至关重要：

craft - 在其他检查前确保导入路径正确
format - 自动修复格式问题
lint - 捕获代码质量问题
type-check - 验证TypeScript语法正确性
test - 确保功能正常运行

每一步都依赖上一步执行通过。

Common Workflow Mistakes

常见工作流错误

Mistakes to avoid:

❌ Using
```
bun test
```
instead of
```
bun run test
```
❌ Forgetting
```
bun run craft
```
after file operations
❌ Committing with TypeScript errors
❌ Skipping quality gates
❌ Running quality gates out of order
❌ Committing directly to main/dev branches
❌ Using Node.js APIs instead of Bun APIs
❌ Relative imports instead of barrel files

需避免的错误：

❌ 使用
```
bun test
```
而非
```
bun run test
```
❌ 在文件操作后忘记执行
```
bun run craft
```
❌ 存在TypeScript错误时提交代码
❌ 跳过质量门禁
❌ 打乱质量门禁执行顺序
❌ 直接提交到main/dev分支
❌ 使用Node.js API而非Bun API
❌ 使用相对导入而非barrel files

Quick Reference

快速参考

Before every commit:

bash

bun run quality    # Run all quality gates
git status         # Verify changes
git add .          # Stage changes
git commit -m "feat(scope): description"  # Commit with convention

Starting new feature:

bash

git checkout dev
git pull origin dev
git checkout -b feature/feature-name

每次提交前：

bash

bun run quality    # Run all quality gates
git status         # Verify changes
git add .          # Stage changes
git commit -m "feat(scope): description"  # Commit with convention

开始新功能开发：

bash

git checkout dev
git pull origin dev
git checkout -b feature/feature-name

... make changes ...

bun run quality git commit -m "feat: add feature"


**File operations workflow:**

```bash

bun run quality git commit -m "feat: add feature"


**文件操作工作流：**

```bash

Create new files

...

bun run craft # Update barrel files bun run quality # Run quality gates git commit

undefined

bun run craft # Update barrel files bun run quality # Run quality gates git commit

undefined

Remember

注意事项

Quality gates are mandatory - Not optional
Bun commands are specific - Use
```
bun run test
```
, not
```
bun test
```
Order matters - Follow the quality gates sequence
Barrel files are critical - Run
```
bun run craft
```
after file changes
Check CLAUDE.md - For complete project rules and standards

质量门禁为强制要求 - 而非可选步骤
Bun命令有特定要求 - 使用
```
bun run test
```
，而非
```
bun test
```
执行顺序至关重要 - 遵循质量门禁的执行序列
Barrel files非常关键 - 文件变更后执行
```
bun run craft
```
查看CLAUDE.md - 获取完整项目规则与标准