vimprove: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Vimprove 是一个交互式 Vim 学习网站。核心功能是通过浏览器中的"迷你 Vim 编辑器 + 关卡式练习"来教用户实际操作 Vim 命令。

当前状态: ✅ 重构完成。项目已从单文件原型（tmp/vimprove.html）重构为模块化的 React + TypeScript 架构。

课程范围: 已完成 Chapter 1-6（基础、进阶编辑、行内 find/till、文本对象、搜索/重构），共 28 节课。

版本管理: 版本号在 src/version.ts 和 package.json 中维护，CHANGELOG 见 README.md

Development Commands

npm run dev      # Start dev server at http://localhost:3000
npm run build    # Build for production
npm run preview  # Preview production build
npm run lint     # Run ESLint
npx vitest run --pool=threads # deprecated
# Note: please refer to section "Test Workflow" and use ./utils/vitest-quickcheck.sh to improve efficiency.

Test Workflow

• 默认并行：npx vitest run --pool=threads（避免直接跑无过滤的 npx vitest run，输出过长会淹没上下文）
• 测试输出简化： 重要 使用grep过滤最终结论，避免无用信息淹没上下文。如 npx vitest run --pool=threads [-t <pattern>] 2>&1 | grep -EA20 "Failed Tests|Test Files"
• 测试输出长度：grep -EA20是使用的20行，所获信息不足时，可以根据实际情况适当增加，建议不超过50行
• Parity 单测输出节流：npx vitest run --pool=threads -t "<pattern>" src/core/tests/exhaustiveTest.*.test.ts 2>&1 | grep -EA20 "Failed Tests|Test Files"，避免海量 skip 日志淹没上下文
• exhaustive parity 分片：src/core/tests/exhaustiveTest.{0..7}.test.ts 使用 getShardCases 按索引取模分片（总 shard=8），并行示例：npx vitest run --pool=threads src/core/tests/exhaustiveTest.*.test.ts --maxWorkers=8
• 快速检查脚本：bash utils/vitest-quickcheck.sh [<test_glob>]（tap-flat + bail，默认跑全部，可传入路径/模式，成功输出 ok ✅，失败时列出前 5 条 not ok）
• 深入排查（exhaustive parity）：
  • 生成 JSON 报告：npx vitest run --pool=threads --reporter=json --outputFile tmp/vimParity-report.json src/core/tests/exhaustiveTest.*.test.ts
  • 查看摘要/聚合或按子串过滤：python utils/vimParity-report-viewer.py tmp/vimParity-report.json ["keyword"...]（keyword 为测试名片段，支持多个并且大小写不敏感；工具仅用于 ParityExhaustive）
    • 支持附加参数：--feature paste-after-op、--limit 5、--sort name|feature|line、--details（输出完整断言）
  • 反复调试单用例：npx vitest run --pool=threads -t "<pattern>" src/core/tests/exhaustiveTest.*.test.ts 2>&1 | grep -EA20 "Failed Tests|Test Files"
    • 正则含特殊符号时建议单引号包裹并在内部转义，如 -t 'd\$P\.'