autonomous-rag: Instructions file for Claude Code

Claude Code Configuration

Rules

• Do what has been asked; nothing more, nothing less
• NEVER create files unless absolutely necessary — prefer editing existing files
• NEVER create documentation files unless explicitly requested
• NEVER save working files or tests to root — use /src, /tests, /docs, /config, /scripts
• ALWAYS read a file before editing it
• NEVER commit secrets, credentials, or .env files
• Keep files under 500 lines
• Validate input at system boundaries

Knowledge Graph Navigation (graphify-out/)

This repo has a graphify knowledge graph at graphify-out/graph.json / graphify-out/GRAPH_REPORT.md, built to help Claude and other agents navigate the codebase without reading whole files cold.

• Consult the graph before manually reading unfamiliar files. Before doing an open-ended Grep/Read sweep to orient in an area you don't already know, check GRAPH_REPORT.md's Community Hubs and God Nodes sections first, or run graphify query "<question>" / graphify explain "<NodeName>". Use it to answer "where do I start," "what's the blast radius of touching X," and "what higher-level workflow does this cluster of functions belong to" — then go read the specific files the graph points at, rather than exploring blind. Still verify anything load-bearing against the live file before acting on it — the graph is a map, not a substitute for reading the code you're about to change (see the staleness caveat below).
• After making changes that alter a node's connections — new function calls, new imports, new/removed classes or interfaces, a file added, removed, or substantially restructured — run graphify <path> --update (incremental; only re-extracts changed files) before ending the session, so the graph doesn't silently drift out of sync with what it claims to represent. Small edits that don't change call/import relationships (e.g. fixing a typo, tweaking a log message) don't need this.
• The graph can be stale — check before trusting it. It reflects whatever state existed at the last --update. If something it describes (e.g. a Protocol, a function) turns out not to exist on disk, that means the graph is behind, not that the codebase is wrong — treat it the same way you'd treat any other persisted memory: verify against the live file before acting on a claim from it.
• .graphifyignore at the repo root excludes .remember/ and pytest_temp/. .remember/'s own .gitignore (a bare *) triggers a known bug in graphify's directory-scoped ignore-pattern handling that causes detect()/--update to silently see 0 files repo-wide if not excluded first — don't remove that exclusion without re-verifying the underlying graphify bug is fixed. pytest_temp/ is transient test output, not real repo content.