todo: agents should put a # comment on shell commands saying what they do #meta #todo
When an agent runs a shell command, it should start it with a one-line bash comment saying what the command does, e.g. # move the same_username_operator plans into their own folder and fix links.
Why: on a phone, a long && chain wraps into a full screen of text, and you can't tell at a glance what it's for. A comment on the first line answers that before you start reading. An end-of-line comment is fine for short one-liners, but on a long command it lands below the wrapped text, and it breaks after a trailing \ or on a heredoc terminator line.
Proposed wording for the instruction:
When running a shell command, start it with a one-line bash comment (# ...) saying what it does. For chained commands that do several distinct things, add a short comment before each step, or split them into separate commands.
The second sentence matters too. The command that prompted this switched branches, pulled, unstashed, moved files, rewrote links and checked links, all in one chain. Two or three smaller commands would be easier to review.
Where it goes: user-level agent config (~/.claude/CLAUDE.md or a global AGENTS.md) so it applies in every repo, or the v3 AGENTS.md if we want contributors' agents to follow it too. Not Railspike, since it isn't about the feature workflow.
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:
User-level config (~/.claude/CLAUDE.md, or a global AGENTS.md if other agents read one). Follows Ilya into every repo.
The v3 AGENTS.md, if we want contributors' agents doing it on v3.
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.