Skip to content

README.en.md

Latest commit

 

History

History
84 lines (54 loc) · 2.9 KB

README.en.md

File metadata and controls

84 lines (54 loc) · 2.9 KB

简体中文 | English

Pitfalls Collection

Every tool README has a "Common Pitfalls" quick-reference table. This directory goes deeper: every pitfall follows the Symptom → Cause → Recovery → Prevention format.

Goal: not a filler checklist, but to help you not hit the same trap twice.

Index by Tool

Tool # of pitfalls Topics
Claude Code 8 Context overflow / hallucinated APIs / over-refactoring / fake verification / CLAUDE.md ignored / git amend / plan drift / subagent context
Cursor 8 Composer rogue / Tab blast / .cursorrules too long / @file silent fail / mode confusion / model switching / stale Notepads / stale index
GitHub Copilot 8 Outdated APIs / Agent reads .env / instructions too long / #file vs @workspace / MCP silent fail / IDE differences / free tier throttling / custom roles not discovered
Aider 7 Auto-commit swallows WIP / /add misses deps / model-switch quality drop / lint loop burns tokens / stale map / Architect→Code drift / amend chaos

Other Tools

Windsurf / Gemini CLI / Kiro / Trae / OpenClaw pitfall pages aren't written yet. You're welcome to:

  1. Check if you've hit any pain points with the tool you use
  2. Send a PR using the template below

Template for New Pitfall Pages

File naming: pitfalls/<tool-name>.md (Chinese) + pitfalls/<tool-name>.en.md (English parallel)

Structure:

# <Tool> Pitfalls

> One-line positioning: what's uniquely painful about this tool

## Pitfall 1: One-line title

**Symptom**
What you actually saw (be specific)

**Cause**
Why it happens (in your own words — don't just parrot the docs)

**Recovery**
How to climb out if already stuck (commands / prompts copy-ready > prose)

**Prevention**
How to avoid next time (prompt / config / Hook / Skill)

...(about 8 pitfalls, quality over quantity)

## Contribute a Pitfall
Template: see claude-code.en.md end

## Related
- Link to the tool's own README
- Link to relevant common/ methodologies

Quality Bar

Pitfalls of writing pitfalls (the meta-pitfall):

  • ❌ Tutorial-in-disguise: "how to use it" repackaged as "pitfall" (e.g., "forgetting to save" is not a pitfall)
  • ❌ Paraphrased FAQ: value is in pain you actually hit and actually fixed
  • ❌ Symptom and cause conflated: readers can't tell "is this me?"
  • ✅ Reproducible symptoms: readers can recognize themselves
  • ✅ Concrete recovery: give a command or prompt, not "pay attention"
  • ✅ Copy-pasteable prevention: directly droppable into CLAUDE.md / .cursorrules / settings.json

Related