agent-coding-conventions

A small, growing Claude Code skill of conventions for writing code and using developer tools reliably as an AI coding agent — and, not by coincidence, in a way that helps humans too.

Core belief: "AI-friendly" means the important facts about the code can be recovered by local reading and local reasoning — not "catering to the taste of one specific tool." Tools change, have blind spots, and are short-lived. Local reasoning is durable. Optimizing your code for one tool's index is chasing a shadow.

What's inside

• SKILL.md — the overview: general principles for trusting tools and for keeping code legible to agents.
• references/ — one file per tool or topic:
  • codegraph — how far to trust a code-graph tool's output, its silent false-negative failure mode, and a fully reproduced real case.

More conventions (other tools, language patterns, review practices) will be added over time.

Install

Drop it into your skills directory so the agent can load it on demand:

# user-level (available in all your projects)
git clone https://github.com/ymy88/agent-coding-conventions \
  ~/.claude/skills/agent-coding-conventions

# or project-level
git clone https://github.com/ymy88/agent-coding-conventions \
  .claude/skills/agent-coding-conventions

Reference it from your CLAUDE.md (recommended)

This is a conventions / discipline skill, not a task skill — so an agent tends to under-trigger it: it will happily answer "can I delete this unused code?" directly without ever consulting the skill. In our own triggering tests, description tuning alone left it near 0% for exactly these advisory moments.

The reliable fix is to reference it explicitly from a CLAUDE.md — project-level ./CLAUDE.md, or user-level ~/.claude/CLAUDE.md to cover every project — so it gets consulted whenever it's relevant instead of relying on probabilistic triggering. For example:

Before acting on output from codegraph or any code-graph / static-analysis / indexing tool — especially a negative result ("no callers", "no tests", "dead code", "impact is only these files"), or before changing a design to satisfy a tool — read the agent-coding-conventions skill.