Display Name
trace-my-code
Category
Agent Skills
Sub-Category
General
Primary Link
https://github.com/kgohil/trace-my-code
Author Name
kgohil
Author Link
https://github.com/kgohil
License
MIT
Other License
No response
Description
trace-my-code keeps a living trace of your codebase — its domain language, architecture, end-to-end flow, and reuse patterns — as curated Markdown next to the code (DOMAIN.md, per-module ARCHITECTURE.md, ADRs), and makes a coding agent read it before it writes. It exists to fix two failures: agents rebuild what already exists, and they misread domain jargon and ship plausible-but-wrong code. The skill bootstraps the trace from your code, keeps it current with a drift hook (git/CI) on every change, and applies a reuse-first ladder (reuse → extend → stdlib → native → … → minimum new) before any new code. In a measured run on a real monorepo (same model + feature request, with vs without the trace, n=1): −56% files read, −12% tokens, −20% wall time, and the agent extended the existing function instead of writing a parallel one. Installs as a skill or a Claude Code / Codex plugin; works across ~24 agents.
Validate Claims
Clone https://github.com/kgohil/trace-my-code (public, MIT). Install: npx skills add kgohil/trace-my-code --skill trace-my-code --global (or /plugin marketplace add kgohil/trace-my-code in Claude Code). In any repo, run /trace-my-code to bootstrap the trace, then ask it to plan a feature in a documented module — observe it reads the module's ARCHITECTURE.md + DOMAIN.md instead of crawling source. The reuse-first nudge self-gates (silent in repos with no trace; ~100 input tokens/turn where one exists). The drift hook commits doc refreshes to the working/PR branch, never to main. benchmarks/ documents the cold-vs-trace method and the measured numbers above (labeled n=1, reproducible).
Specific Task(s)
In a repo that has a bootstrapped trace, give the agent a feature request that uses domain jargon and touches a module that already has a relevant helper/gate. Confirm the agent (1) reads the trace to comprehend the jargon, and (2) reuses/extends the existing code rather than creating a parallel implementation.
Specific Prompt(s)
- "Bootstrap the trace for this repo." → produces
DOMAIN.md + per-module ARCHITECTURE.md + seed ADRs, _TODO-flagged where unverified.
- "Tighten the conviction gate so weak-lens cards don't reach compilation." (in a repo with that domain) → the agent reads the trace, finds the existing gate, and extends it instead of writing a new one.
- "Add a CSV export to this page." → the agent reuses the existing export pattern + a native input instead of pulling a new library.
Additional Comments
Free and MIT. No telemetry, no network calls from the skill itself (the optional drift hook in rewrite mode invokes your local Claude CLI and commits docs to the PR branch — never main — and degrades to a comment-only "flag" mode without a credential). The reuse-first hook is a soft reminder, not a hard gate, and self-gates to repos that have a trace. Inspired by Andrej Karpathy's "LLM Wiki" idea and ponytail's reuse ladder. Note: the repo first went public on 2026-06-22, so it crosses the "one week since first public commit" bar on ~2026-06-29 — happy for you to validate then.
Recommendation Checklist
Display Name
trace-my-code
Category
Agent Skills
Sub-Category
General
Primary Link
https://github.com/kgohil/trace-my-code
Author Name
kgohil
Author Link
https://github.com/kgohil
License
MIT
Other License
No response
Description
trace-my-code keeps a living trace of your codebase — its domain language, architecture, end-to-end flow, and reuse patterns — as curated Markdown next to the code (
DOMAIN.md, per-moduleARCHITECTURE.md, ADRs), and makes a coding agent read it before it writes. It exists to fix two failures: agents rebuild what already exists, and they misread domain jargon and ship plausible-but-wrong code. The skill bootstraps the trace from your code, keeps it current with a drift hook (git/CI) on every change, and applies a reuse-first ladder (reuse → extend → stdlib → native → … → minimum new) before any new code. In a measured run on a real monorepo (same model + feature request, with vs without the trace, n=1): −56% files read, −12% tokens, −20% wall time, and the agent extended the existing function instead of writing a parallel one. Installs as a skill or a Claude Code / Codex plugin; works across ~24 agents.Validate Claims
Clone https://github.com/kgohil/trace-my-code (public, MIT). Install:
npx skills add kgohil/trace-my-code --skill trace-my-code --global(or/plugin marketplace add kgohil/trace-my-codein Claude Code). In any repo, run/trace-my-codeto bootstrap the trace, then ask it to plan a feature in a documented module — observe it reads the module'sARCHITECTURE.md+DOMAIN.mdinstead of crawling source. The reuse-first nudge self-gates (silent in repos with no trace; ~100 input tokens/turn where one exists). The drift hook commits doc refreshes to the working/PR branch, never tomain.benchmarks/documents the cold-vs-trace method and the measured numbers above (labeled n=1, reproducible).Specific Task(s)
In a repo that has a bootstrapped trace, give the agent a feature request that uses domain jargon and touches a module that already has a relevant helper/gate. Confirm the agent (1) reads the trace to comprehend the jargon, and (2) reuses/extends the existing code rather than creating a parallel implementation.
Specific Prompt(s)
DOMAIN.md+ per-moduleARCHITECTURE.md+ seed ADRs,_TODO-flagged where unverified.Additional Comments
Free and MIT. No telemetry, no network calls from the skill itself (the optional drift hook in rewrite mode invokes your local Claude CLI and commits docs to the PR branch — never
main— and degrades to a comment-only "flag" mode without a credential). The reuse-first hook is a soft reminder, not a hard gate, and self-gates to repos that have a trace. Inspired by Andrej Karpathy's "LLM Wiki" idea and ponytail's reuse ladder. Note: the repo first went public on 2026-06-22, so it crosses the "one week since first public commit" bar on ~2026-06-29 — happy for you to validate then.Recommendation Checklist