docs: rewrite CLAUDE.md in descriptive register, drop directives#23
Merged
Conversation
The previous CLAUDE.md ran on imperatives ("MANDATORY", "Using grep
is always wrong here", "Never invoke without --json", "Never guess
fqnames", "Do not read source files"). That register is the same
prompt-injection-adjacent shape that was rewritten out of the
cli-bridge AGENTS.md: documentation that gets auto-loaded into an
agent's context every time it works in the repo, written as if it
were issuing runtime instructions to the model.
Rewritten as a working reference: what gosymdb does for navigation,
how to bootstrap a session, the task-to-command table, fqname
resolution, a typical exploration sequence, the common failure modes
(unchanged in substance — they were already factual), stale-index
recovery, and the convention for keeping this file in sync with code.
The Wrong/Right comparison table is gone; the same information is
present as a Task/Command table without the coercive framing. The
"Using grep ... is always wrong here" header is gone too — the
descriptive equivalent ("Grep finds string occurrences; gosymdb
finds resolved symbols. The two answer different questions") sits
in the navigation section without telling the agent what to do.
Net change: -97 / +47 lines. Same content surface, no behavioral
directives.
walkindude
force-pushed
the
docs/claude-md-descriptive-register
branch
from
8f1f951 to
eb2a044
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The repo's
CLAUDE.mdwas running on imperatives directed at agents: "MANDATORY", "Using grep is always wrong here", "Never invoke without--json", "Never guess fqnames", "Do not read source files". That register is the same prompt-injection-adjacent shape that was rewritten out of cli-bridge's AGENTS.md. When a doc gets auto-loaded into an agent's context on every session in the repo, it should describe what the tool does and how the conventions work, not issue runtime instructions to the model.This rewrite keeps the same content surface (session bootstrap, navigation tasks, fqname resolution, exploration sequence, failure modes, stale-index recovery, keeping the file current) and drops the coercive framing.
find/defas the reliable source.error_code/hint/note/valid_subcommands).Net: −97 / +47 lines. Same usefulness for an agent working in this repo, less directive register.
Test plan
CLAUDE.mdon GitHub and confirm formatting (tables, code fences) surviveerror_code: no_databaseshows up, when to rebuild vs--auto-reindexinternal/cmd/agentcontext.go,indexer/stale.go)🤖 Generated with Claude Code