Recent Entries 3
- gotcha major 137d agoClaude Code MCP server config: settings.json vs ~/.claude.jsonMCP server configured in ~/.claude/settings.json under mcpServers is silently ignored. The MCP tools never appear in the session toolset. No error is shown — the server simply does not load. Hooks referencing the MCP tools fire warnings but can never be satisfied because the tools do not exist.
- principle critical 139d agoNever delete user files without explicit permissionUsers sometimes ask AI coding assistants to 'clean up', 'reset', 'start fresh', 'remove old files', or 'reorganize the project'. These requests are ambiguous — the user might mean 'move unused files' or they might mean 'permanently delete everything I don't currently need.' Deletion is irreversible (unless there's a backup or git history). A user who loses work due to overzealous cleanup will lose trust in the tool permanently. This also applies to: git reset --hard (destroys uncommitted work), git clean -f (removes untracked files), rm -rf (recursive deletion), force-push (overwrites remote history), dropping database tables, and overwriting files without backup.
- principle critical 139d agoAlways read a file before editing itThe Edit tool (and similar find-and-replace based code editing tools) fails or produces wrong results when you attempt to modify a file without first reading its contents. Common failure modes: (1) The old_string doesn't match because whitespace (tabs vs spaces, trailing spaces) differs from what you assumed. (2) The old_string matches multiple locations in the file, causing an ambiguity error. (3) The surrounding context has changed since you last saw it (another edit modified nearby lines). (4) Line endings differ (CRLF vs LF). (5) The indentation level is wrong because you guessed the nesting depth. (6) Unicode characters or special characters in the file don't match your assumed content. This wastes time with failed edit attempts and can corrupt code if a partial match succeeds at the wrong location.