Agent coding conventions
Conventions for writing code and using developer tools reliably as an AI coding agent. A Claude Code skill.
npx -y skills add ymy88/agent-coding-conventionsAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Conventions for writing code and using developer tools reliably as an AI coding agent. Use when judging how far to trust a code-intelligence / static-analysis / indexing tool's output (e.g. codegraph) — especially negative claims like "no callers", "no covering tests", "impact is only these files"; or when a design choice (factory vs public constructor, DI, reflection, dynamic dispatch) affects how legible the code is to an agent. Consult BEFORE trusting a tool's claim as fact, and BEFORE changing a design to satisfy a tool.
SKILL.md
2.9 KB, as published. Nobody here has run it
Agent coding conventions
An overview of conventions for working in a codebase as an AI agent: how to use developer tools without being quietly misled by them, and how to write code that stays legible to the next agent.
Core belief: "AI-friendly" = the important facts are recoverable by local reading and reasoning — not "catering to one tool's index." Tools have blind spots and are short-lived; local reasoning is durable.
General principles
- Evidence over vibes — don't guess, verify. Back any load-bearing claim with a primary source (read the code, run the test, check the docs). When you infer from black-box behavior ("this is probably how the tool decides X"), say so and state your confidence rather than asserting it as fact.
- Tools are lead generators, not oracles. A tool takes you to the right place cheaply; it doesn't convict — promote a lead to a fact only after first-hand confirmation.
- Trust positive claims over negative ones. "Not found / none / only these" are completeness claims — what tools are worst at. "Not listed" ≠ "doesn't exist."
- Negative failures are silent — verify them. A wrong pointer self-corrects; a missing fact does not announce itself.
- Scale verification to the stakes. Act on low-stakes leads directly; confirm high-stakes claims independently.
- Don't mutilate a design to satisfy a tool's blind spot — that's overfitting plus a lifespan mismatch. Fix the tool or your discipline, not the code.
- The real "AI-unfriendly" smell is reasoning-opacity (reflection, stringly-typed wiring, runtime-DI magic, heavy metaprogramming), not a missing tool edge. Test: "can a reader determine behavior from a small local slice?"
Conventions
Read the relevant entry before the matching task. This list grows over time.
| Topic | When to read |
|---|---|
| codegraph | Before relying on codegraph's output |
| codegraph vs LSP | When both codegraph and an LSP (tsserver, pyright, …) are available — which to trust for callers / references / types |
Every convention is backed by a reproducible observation. Black-box inferences say so and state confidence — the same "don't guess, verify" bar you hold yourself to.