How Do I Read .brass/ai_instructions.yaml?
After a BrassCoders scan, .brass/ai_instructions.yaml contains severity-ranked findings formatted for pasting into Claude Code or Cursor. Here's how to read and use it.
The Structure of ai_instructions.yaml
BrassCoders writes ai_instructions.yaml as a ranked list of findings — each entry has a title, severity level (CRITICAL / HIGH / MEDIUM / LOW), confidence score, the exact file path and line number, the scanner that found it, and a one-sentence description written for an AI reviewer.
After brasscoders scan ., open .brass/ai_instructions.yaml. The file is plain YAML (https://yaml.org/spec/1.2.2/) — readable in any text editor, parseable by any YAML library.
Findings appear in severity order: CRITICAL findings first, then HIGH, MEDIUM, LOW. Within each severity band, findings are ranked by confidence. The top of the file is where the real bugs cluster.
The OSS core applies heuristic deduplication, so a typical 1,500+ raw finding scan produces a few hundred entries in ai_instructions.yaml. BrassCoders Paid adds semantic deduplication that reduces that to roughly 30 actionable entries.
How to Use It With Claude Code or Cursor
BrassCoders formats ai_instructions.yaml for direct paste into Claude Code (https://docs.anthropic.com/en/docs/claude-code) or Cursor — the AI assistant reads the ranked finding list and triages each one against the actual source file, providing a source-verified verdict and fix.
The intended workflow:
- Run
brasscoders scan . - Open Claude Code or Cursor in your project directory
- Paste the contents of
.brass/ai_instructions.yamlinto the conversation - Ask: “Triage these findings and identify which are real bugs”
Claude Code or Cursor reads the file paths and line numbers, opens the referenced source files, and evaluates each finding in context. It distinguishes real bugs from false positives, explains why each finding matters, and proposes a fix. This is the intended division of labor: BrassCoders provides the structured, deterministic finding list; the AI assistant provides the context-aware triage.
The .brass/ directory is regenerated on every scan — add it to .gitignore if you don’t want to commit scan output to version control.
Install BrassCoders with pip install brasscoders and run brasscoders scan . from your project root. The OSS core is free and Apache 2.0 licensed. BrassCoders Paid adds semantic noise reduction for $12/dev/month.
Frequently Asked Questions
What's the difference between ai_instructions.yaml and detailed_analysis.yaml?
ai_instructions.yaml is short and ranked — designed for pasting into Claude Code or Cursor. It contains the most important fields per finding: title, severity, confidence, file_path, line_number, scanner, description. detailed_analysis.yaml contains every finding with full context, evidence strings, and scanner metadata — useful for custom tooling or deeper review.
How do I use ai_instructions.yaml with Claude Code?
Open Claude Code in your project directory, paste the contents of .brass/ai_instructions.yaml into the conversation, and ask it to triage the findings. Claude Code reads the file paths and line numbers, opens the referenced source files, and provides a source-verified verdict and fix for each finding.
Why is the file called ai_instructions.yaml?
Because it's structured as instructions for an AI assistant — not a human-readable report. The format is optimized for the consumption pattern where an AI assistant reads the finding list and opens the referenced source files to evaluate each one in context.
How many findings will ai_instructions.yaml have?
On the OSS core, typically a few hundred after heuristic deduplication — depends on project size and how many issues the scanners find. On BrassCoders Paid, semantic deduplication against your project signature reduces the list to roughly 30 actionable findings. The number at the top of the severity ranking (CRITICAL and HIGH) is usually small — those are the findings worth acting on immediately.