Learn My Code

The uncomfortable part of building with agents

I can ask a coding agent to build a feature, watch the tests pass, and still be unable to explain the most important branch when somebody asks me about it the next day. The code exists. The product may even work. But ownership is weaker than the commit history suggests.

This is especially visible in a project interview. “I built this” quickly becomes a request to trace one input, defend one design choice, describe a failure mode, or explain how AI-generated code was verified. A long AI explanation does not reliably prepare me for that moment. Reading feels familiar; prediction reveals whether the mental model is actually there.

I built Learn My Code around that gap. It is an open-source agent skill for Claude Code and OpenAI Codex that studies the code already in a Git repository and turns it into active-recall lessons. The central rule is deliberately restrictive: the agent asks one grounded question, waits for the learner’s reasoning, corrects only the smallest missing piece, and then tests the model again.

What actually happens when you invoke it

1. Resolve the learning scope.The skill uses an explicit file, commit, range, staged diff, or working tree when requested. With no scope, it starts from recent branch changes plus staged, unstaged, and safe untracked files.
2. Collect a bounded snapshot.collect-diff.sh asks Git for changed text files, excludes common credential paths, binaries, lockfiles, generated directories, and agent state, then counts both files and changed lines.
3. Refuse an oversized lesson.More than 15 files or 800 changed lines is not silently sampled. The learner must choose two or three files, because a vague lesson over a large repository is unlikely to produce a useful question.
4. Inspect enough surrounding code.The agent reads callers, types, tests, and nearby implementation only as needed to establish the execution path. It is not supposed to invent facts from names or commit messages.
5. Ask one spoiler-resistant question.The first study question predicts one observable output or next step for a concrete input. It contains exactly one question mark and does not reveal the changed condition, test assertion, answer outline, or a scope summary first.
6. Grade the reasoning.After the learner answers, the agent returns Solid, Partial, or Miss, gives a one-sentence reason, supplies the smallest correction, and asks the next single question.
7. Stop before it becomes a lecture.A session ends after at most six questions or immediately when the learner says done. The recap distinguishes what appears owned, what remains shaky, and one useful next exercise.

A concrete example

Suppose an agent changed an authentication helper. A normal explanation might summarize the refresh path and point to the test. Learn My Code avoids doing that first. It may instead ask:

For an expired session at src/auth/session.ts:48, what observable value reaches the route handler?

The learner must trace the code. If the answer reaches the right outcome but misses the cookie-write boundary, the response is Partial: the final direction is correct, but one meaningful condition is missing. The correction should be smaller than a lecture. The next question then probes the corrected model with a failure case.

The system grades an answer against inspected code; it does not grade the person or turn a disagreement into a code-quality review. If the repository cannot settle a claim, the agent should say so.

Questions are designed, not improvised

The skill defines five useful question shapes. A prediction asks what happens for one concrete input. A trace follows a value through two or three boundaries. A failure-mode question breaks an assumption. A blast-radius question identifies the first caller, type, cache, schema, test, or UI state that must agree with a change. A reversal asks what would change under one plausible alternative.

It rejects trivia, broad prompts such as “explain this file,” questions about code the agent did not inspect, and multi-part prompts disguised as one question. It also prevents the agent from showing both sides of a diff or quoting a test assertion before the learner predicts the behavior. That “spoiler resistance” is tested as a host-level acceptance scenario.

It can also prepare the project defense

Study mode is only one of three modes. Interview preview produces five to eight questions that a reviewer could reasonably derive from the repository. Each question states which file or behavior prompted it and which two or three topics a strong answer should cover, without writing a script for the learner to memorize.

Mock interview mode asks one question at a time and follows the learner’s own claims. It can move from project scope to a request flow, a design alternative, a failure mode, scaling constraints, and finally how AI-generated code was reviewed. The feedback separates technical misunderstanding from presentation weakness and marks unsupported claims that should be removed or verified.

The important constraint is evidence. If the repository contains no traffic measurements, production incident, team history, or documented personal contribution, the skill must not manufacture one to make the interview sound impressive.

The local and read-only boundary

Learn My Code uses the coding agent already open in the repository. It requires no separate learning account, server, source-code upload, or additional API key. The collector reduces the scope before the model sees it and excludes common secret-bearing paths, but the documentation is careful not to describe regular-expression filtering as a security guarantee.

Source files remain read-only during a lesson. A small coding challenge may be offered only after the learner has explained the relevant behavior. Even then, the default is to state the expected result and verification command, leaving the learner to make the change. The agent edits code only after an explicit request.

Optional progress tracking is enabled only when .learn-my-code/ already exists or the learner asks for it. The stored record contains concepts, verdicts, review intervals, and compact corrections—not source code, diffs, secrets, or full free-form answers.

How the Git collector works

The bundled Bash collector first verifies that the current directory belongs to a Git worktree. It resolves staged changes, the working tree, a revision range, the last N commits, or a default base from the upstream merge base, previous commit, or empty tree.

It filters paths before constructing the snapshot. Environment files, keys, certificates, credential-like names, package locks, agent configuration, previous learning state, generated directories, vendored dependencies, images, archives, PDFs, and fonts are excluded. Untracked text files may be included for working-tree lessons. The resulting patch is capped by file and changed-line counts, and a final redaction pass catches several familiar token and credential patterns.

This is context minimization, not a sandbox. Arbitrary source can still contain sensitive material under an innocent filename. A safe tool should make its boundary visible rather than turn a useful filter into an absolute promise.

Installation and daily use

The repository contains one canonical cross-agent skill and an installer that copies it into the user or project skill directory for Claude Code, Codex, or both. The installer refuses to overwrite an existing installation unless --force is supplied.

git clone https://github.com/nightandweather/learn-my-code.git
cd learn-my-code
./install.sh --both --user

Then, inside another Git repository, a lesson can begin with natural language or the host’s explicit skill syntax:

Quiz me on the code I just changed.
$learn-my-code quiz me on my current changes
/learn-my-code run a mock backend interview

During a lesson, hint, skip, tell me, harder, easier, and done adjust the interaction without turning it into an unrestricted chat.

Export is a separate operation

Question sets can be prepared for local Markdown, GitHub Pages, Notion, or Slack. The default export contains questions only—not source diffs, absolute local paths, the learner’s verbatim answers, or full results. Direct publication requires the relevant connected integration and a verified destination. Otherwise the skill creates share-ready Markdown without pretending it posted anything.

What is implemented, and what is not proven

The repository includes the canonical skill, installer, diff collector, question and interview policies, export guidance, progress format, CI, shell tests, and host-level acceptance scenarios. Its core study, interview, and export workflows are usable now in Claude Code and Codex.

It is still an instruction-based agent skill. Exact wording and lesson quality vary by host, model, repository, and task. The tests verify installation, scope collection, safety boundaries, and expected interaction properties; they do not prove that every generated question teaches effectively. Before calling it a finished 1.0 learning product, I want more real lesson examples, language diversity, repository-size testing, and evaluations of whether learners can still explain the code later without the agent.

The larger experiment

Learn My Code is my response to a broader question: if agents make software production dramatically faster, what helps a person retain technical ownership of the result? The answer is probably not to reject generated code, and it is not to request an even longer generated explanation. My current hypothesis is smaller: inspect the learner’s real change, ask for a prediction before revealing the answer, revisit weak concepts, and practice defending the actual project.

The code can be written with help. The reasoning still has to become yours.