Dev Pitfalls

Common Dev Pitfalls (check the layer before debugging it)

These cost hours because the symptom points at the wrong thing, and they're easy to "fix" by going in circles. When something matches below, check the cause here before debugging the code.

Check project state before acting

Claude's frequent miss is assuming project state instead of verifying it. Two checks, stated plainly to the user:

• Is it even a git repo? Before staging, committing, or diffing, confirm the repo exists (git rev-parse --is-inside-work-tree). If it doesn't, say so directly, "this directory isn't a git repository yet, run git init first", rather than running git commands that fail confusingly or silently acting on a parent repo.
• Is node_modules ignored? Before the first commit, confirm .gitignore exists and lists node_modules/. Create .gitignore BEFORE npm install so it is never tracked. If it isn't ignored yet, say so before anything gets committed.

.gitignore only ignores UNtracked files. If node_modules (or .env, or build output) was already committed, adding it to .gitignore changes nothing, git keeps tracking it, and this is a classic "my .gitignore isn't working" loop. Untrack it, then commit:

git rm -r --cached node_modules
git commit -m "Stop tracking node_modules"

Confirm a rule actually bites with git check-ignore -v node_modules. Committed node_modules bloats the repo and breaks CI, its platform-specific compiled binaries fail on Linux runners. Same fix for anything that "won't stop showing up" after you ignored it.

WSL: put the project on the Linux filesystem, not /mnt/c

The single biggest WSL pitfall, and Claude rarely thinks to check it. A project under /mnt/c (any Windows drive) is reached from Linux over a 9P bridge, so:

• file operations run 10-100x slower, npm install, git status, and test runs crawl
• inotify is flaky across the bridge, so file watchers fire intermittently, hot reload and test watchers "work randomly" then silently stop, which becomes a circular debugging session if you chase it as a config problem
• Linux permission bits are only emulated, chmod +x can silently fail and ssh rejects keys as "bad permissions"
• editor integration breaks: Claude often can't see your active selection or the code you've highlighted, so it's working blind on what you're pointing at

Keep repos on the Linux side (~/projects/..., ~/code/...) and open them with VS Code Remote-WSL. If a project sits on /mnt/c and shows any of the above, that location IS the bug, move it:

mv /mnt/c/Users/<you>/projects/my-app ~/projects/

Use /mnt/c only when a file genuinely needs to live on the Windows side for a Windows GUI app.

Don't chase this through settings. The circular trap is treating intermittent watchers or a blind editor as a config problem and tweaking watcher polling, exclude globs, and a pile of VS Code settings. On a Windows machine showing these symptoms, check the path FIRST. If it's /mnt/c, the answer is almost always "you're on the Windows filesystem, open the folder in WSL (Remote-WSL) and move it to ~/", say that before suggesting a single setting.

Opening a browser from WSL (auth / SSO)

A CLI runs an OAuth/SSO login, tries to open a browser from WSL, and either nothing opens or it opens a browser that isn't signed into the corporate IdP (Okta, Entra), so the login fails. Why your own browser matters: the SSO session lives in your real Chrome profile, a fresh or other browser context doesn't have it.

Default to launching your real Chrome via an executable shim on PATH (~/.local/bin/chrome, chmod +x):

#!/bin/sh
exec "/mnt/c/Program Files/Google/Chrome/Application/chrome.exe" "$@"

export BROWSER=chrome   # in ~/.bashrc

That opens your actual browser, your bookmarks and your live Okta session, which is what you want about 99% of the time.

wslview (from the wslu package) is the alternative, but in a corporate setup the browser it routes to may not carry your IdP session, so the login page loads unauthenticated. Offer it as a fallback, not the default. If neither is configured, ask the user which they want (own Chrome vs wslview) before wiring it in.

Check $BROWSER hasn't been hijacked. BROWSER has two unrelated meanings: the desktop convention (which browser opens URLs, used by auth flows) and Playwright's test-runner convention, where BROWSER=chromium selects which browser to run tests in. If a Playwright project exports BROWSER=chromium globally (in ~/.bashrc or a sourced .env) instead of setting it inline on the test command, it overrides your desktop browser, so auth flows either fail outright (no executable named chromium on PATH) or open Playwright's bundled Chromium, a clean isolated context with none of your sessions. Same class of problem as VS Code's built-in browser. Diagnose with echo $BROWSER: if it shows chromium, firefox, or webkit, that's the hijack. Keep BROWSER=chrome (your shim) for desktop and auth, and scope Playwright's to the command only: BROWSER=chromium npx playwright test.

Use a shim, not a bash alias. An alias exists only in interactive shells, so when a program execs $BROWSER it never sees the alias and the open silently fails, which is the exact programmatic case auth needs.

Line endings: LF everywhere (CRLF is the silent killer)

Windows CRLF breaks things in ways that take forever to trace: YAML parsing wrong, shell scripts dying with bad interpreter: /bin/bash^M, Docker entrypoints not executing, diffs showing every line changed when nothing did. YAML and .sh scripts are the usual victims because a stray \r rides along invisibly.

The symptom that wastes the most time: a deploy failing with a type error. A Kubernetes apply (or any YAML-driven deploy) that throws "expected a string, got a map/object" or "cannot unmarshal object into ... string" usually has nothing wrong with the field it names. A stray \r from CRLF has broken how the parser reads the value, so a scalar gets read as a structure. The manifest looks correct because the \r is invisible, which is exactly why this eats hours: the error points at the data, not the line ending. Before debugging the field, the schema, or the value, check the file's line endings, normalize to LF and re-apply.

Make the repo LF-only with .gitattributes at the root:

* text=auto eol=lf

text=auto lets git detect text vs binary (binaries untouched); eol=lf forces LF in both the committed blob and the working tree, regardless of anyone's local core.autocrlf. For a repo that already committed CRLF, the attribute alone won't rewrite it, renormalize once: git add --renormalize . && git commit -m "Normalize line endings to LF". Set .editorconfig end_of_line = lf so files are authored as LF too.