---

The problem

AI agents made everyone faster. They also made it easy to ship a feature you cannot explain in a code review.

People call this vibe coding — accepting generated code because it works, without understanding why. It feels productive right up until you have to debug it, defend it in an interview, or extend it six months later.

Learn As You Build is the antidote. Same speed. You just come out the other side actually knowing something.

---

Proof: real sessions, unedited

These are real screenshots from real work — not mockups.

Naming a concept the user could only describe

The situation: worrying that an app's privacy label meant crash reports weren't being collected.

The teaching line at the bottom:

"What you were worried about is called crash diagnostics/telemetry — you have it; Apple's "tracking" is cross-app advertising tracking — a different thing entirely."

One sentence turned a vague worry into two precise terms — and resolved the actual confusion.

Naming the distinction behind a real architecture decision

The situation: deciding whether to enable Firebase's checkRevoked on every request.

The teaching line:

"The concept you were reaching for is session lifetime vs revocation latency. You want long session lifetime (you have it, permanently). checkRevoked only tunes revocation latency."

That distinction is the entire decision. Without those two terms it's a coin flip; with them the answer is obvious.

It works outside of code too

The situation: planning how to make this very repo credible to strangers.

The teaching line:

"What you're describing is called social proof — evidence that other people (or in this case, real usage) validate a claim. For a repo specifically it's 'proof of use,' and it's the single biggest driver of trust for an unknown project."

Marketing, not engineering — the rules trigger on description, not on programming.

That's the whole product. Every term also gets logged to GLOSSARY.md with the situation it came from.

---

How it works

Two rules. Both always on. Neither blocks the work.

Rule 1 — It names what you can only describe

You understand the concept. You don't have the word. The word is what lets you search it, reuse it, and say it in a meeting.

You say	It replies
"I want the button to feel like it's pushing back."	That's haptic affordance — a physical cue confirming input was registered.
"Why does the second one feel cheaper at the same price?"	Anchoring — the first number becomes the ruler for everything after.
"It's slow because we hit the database once per row."	That's the N+1 query problem. Batching it now.

Rule 2 — It explains the reasoning, not just the change

• Why, not what — "Absolute path to node here: GUI apps launched from Finder don't inherit your shell PATH."
• The tradeoff — "Optimistic updates feel instant, but you now own rollback logic."
• The pattern — "This is the repository pattern — logic talks to an interface, not the database."
• The transfer — "Same as debouncing search: any fast trigger driving an expensive operation gets throttled."

That last one is the highest-value move. It turns one fix into a tool you keep.

Rule 3 — It logs everything

### Loss Aversion
**Field:** Psychology
**Definition:** Losing something hurts about twice as much as gaining the same thing feels good.
**Came up when:** Rewriting an upgrade prompt to show the files about to be deleted
                  instead of the features to be gained.
**Date:** 2026-08-14

A definition alone is a flashcard you forget. A definition attached to the afternoon you rewrote that screen is a memory. That's the design.

---

Install

One command

git clone https://github.com/Fred-In-tech/learn-as-you-build.git
cd learn-as-you-build && ./install.sh

Auto-detects your agents and wires each one up. Safe to re-run.

Manual, per platform

Platform	File	Install
Claude Code	CLAUDE.md + skills/	cat CLAUDE.md >> ~/.claude/CLAUDE.md and copy skills/ to ~/.claude/skills/
Codex	AGENTS.md	cp AGENTS.md ~/.codex/AGENTS.md
Gemini CLI	GEMINI.md	cp GEMINI.md ~/.gemini/GEMINI.md
Cursor	.cursor/rules/*.mdc	Copy to your project's .cursor/rules/ (alwaysApply: true)
Windsurf	.windsurfrules	Copy to project root
Cline	.clinerules	Copy to project root
Zed · Copilot · OpenCode · other	AGENTS.md	Copy to project root

Plain Markdown, no tool-specific syntax — it drops into anything that reads an instruction file.

---

Using it

Nothing to invoke. Work normally.

Ask	Get
"What have I learned?"	Summary by field, newest first
"What was that term about pricing?"	The entry, with its original context
"Show my glossary"	Everything, grouped
"Quiz me"	Definition shown, term hidden — you name it

---

FAQ

What is Learn As You Build? A set of instruction files that make any AI coding agent teach you while it works — naming technical concepts, explaining tradeoffs, and building a personal glossary from your real sessions.

Which AI coding assistants does it support? Claude Code, OpenAI Codex, Cursor, Gemini CLI, Windsurf, Cline, Zed, GitHub Copilot, and OpenCode — anything that reads AGENTS.md or an equivalent instruction file.

Will it slow down my coding? No. Explanations ride alongside the work and are never a prerequisite for it. Routine changes get silence; only genuinely new or non-obvious things get a line or two.

Is this the same as an AI tutor? No. A tutor gives you exercises. This teaches from your actual work — the feature you're shipping right now — which is why it sticks. The technical term is just-in-time learning.

What is vibe coding, and how does this help? Vibe coding is accepting AI-generated code because it runs, without understanding it. This keeps the speed but closes the understanding gap, so you can defend your code in review or in an interview.

Does it send my data anywhere? No. The glossary is a local Markdown file. Nothing is transmitted. If you publish yours, context lines are genericized first.

Can I use it for non-coding work? Yes. The rules cover design, marketing, product, psychology, business, and film/video. It triggers on description, not on programming.

How is this different from just asking the AI to explain things? Asking is manual and you only ask about what you already know to question. This is automatic and catches the things you didn't know you didn't know — which is where the real gaps are.

---

Design principles

The main way tools like this fail is by becoming annoying. These rules prevent that:

• Never slow the work — teaching rides alongside, never blocks
• No lecturing — past ~3 lines it asks first
• Never invent a term — if no real word exists, it says so. A confidently-taught fake term will embarrass you in front of an expert
• Verify before teaching — a wrong fact taught confidently is worse than silence, because you'll repeat it
• Explain its own mistakes — corrected errors teach hardest
• Depth scales with novelty — routine gets silence, surprising gets explained

---

What's in the box

AGENTS.md          canonical rules — Codex, Zed, Copilot, OpenCode
CLAUDE.md          Claude Code
GEMINI.md          Gemini CLI
.cursor/rules/     Cursor (alwaysApply)
.windsurfrules     Windsurf
.clinerules        Cline
skills/
  concept-glossary/     naming + logging
  learn-as-you-build/   reasoning + tradeoffs
GLOSSARY.md        live 25-term example from real sessions
install.sh         auto-detecting installer

---

Star history

---

Contributing

Issues and PRs welcome. Especially valuable:

• Screenshots of it working — real proof beats any description
• Support files for agents not yet covered
• Better phrasings that reduce noise

---

License

MIT — use it, fork it, ship it.