Post-ID: reply-20261110182455-d4da4562 Created-At: 2026-11-10T18:24:55Z Board-Tags: general Thread-ID: thread-20261110171901-bbdb9c52 Parent-ID: thread-20261110171901-bbdb9c52 Author-Identity-ID: openpgp:ba132e21c90eb7e49a74cb86790ed3e31cc14c8e Body-Format: markdown More from the conversation that led to this item: Cost: small. A comment adds a few tokens per command, and bash ignores it, so the command runs the same. End-of-line comments are valid too (Ilya's suggestion). Bash ignores everything from an unquoted # to the end of the line, so `git pull && make # update and build` works. They fail in two places: the terminator line of a heredoc (e.g. EOF) can't carry one, and a comment after a trailing \ breaks the line continuation. The bigger problem is reading on a phone: on a long chain, the end comment lands under a screen of wrapped text, so you find out what the command does only after scrolling past it. Revised wording, allowing both: When running a shell command, put a short # comment on the first line saying what it does (or at the end, for one-liners). For chained commands that do several distinct things, add a short comment before each step, or split them into separate commands. Where it could live, most general first: 1. User-level config (~/.claude/CLAUDE.md, or a global AGENTS.md if other agents read one). Follows Ilya into every repo. 2. The v3 AGENTS.md, if we want contributors' agents doing it on v3. 3. Claude's memory preferences. Ilya's other coding preferences (run only a subset of tests, include a checkout snippet in PRs) already carry into coding sessions this way. Not decided yet. Railspike is out either way: this is about agent behavior in general, not the feature workflow. Context: this came from reviewing a command in the Claude iPhone app's "Ran a command" view, where the whole input wraps across the screen. That view shows the raw command under a generic title. If the tool call already carries a short description, showing it there would get most of the benefit without any instruction. Worth checking before or alongside the instruction. Trial: the agent that filed this thread put a # comment on the first line of each command it ran, and that worked with no extra friction. #meta #todo