---

The big idea

You don't get senior by reading, and you don't get senior by watching an AI build it for you. You get there by building the real thing yourself, hitting real friction, with someone experienced nearby.

atelier turns that into a repeatable setup. Point it at any idea — a side project, a thing you want to understand, a domain you've never touched — and it becomes your curriculum. The AI becomes the mentor: it explains concepts from first principles, designs build guides, reviews your decisions, and deliberately leaves the interesting parts for you to figure out.

And because not everyone learns the same way — or has the same energy on a given day — how much code the AI writes is a dial you control, from "I type every line" to "build it for me and teach as you go."

The product matters. Your learning matters more. When they conflict, learning wins.

---

⚡ 60-second start

# 1. Use this template (or fork it), then clone your copy
git clone https://github.com/<you>/<your-project>.git
cd <your-project>

# 2. Open it in your AI tool of choice…
claude          # Claude Code
cursor .        # Cursor
code .          # VS Code + Copilot
gemini          # Gemini CLI
codex           # OpenAI Codex CLI

# 3. …and just say:
#    "start"

That's it. The AI notices this is a fresh template, welcomes you, and runs a short onboarding interview — what you're building, what you already know, what you want to learn, and how much code you want it to write. Ten minutes later you have a customized workspace, a roadmap, and your first build step.

🟢 Tip: use this repo as a GitHub template (the green “Use this template” button) so each new idea gets a clean copy.

---

How it flows

flowchart TD
    A([Fork / use template]) --> B["Open in your AI tool<br/>and say <b>start</b>"]
    B --> C{{"Onboarding interview<br/>idea · background · goals · mode"}}
    C --> D[["Workspace set up:<br/>PROJECT.md · design skeleton · roadmap"]]
    D --> E["<b>/milestone</b><br/>get the next build guide"]
    E --> F["You build it<br/>(how much you vs. AI = the mode)"]
    F --> G["<b>verify</b> it runs ✅"]
    G --> H["<b>/progress</b><br/>log the win · plan next"]
    H --> E
    F -.deep dive worth keeping.-> I[("learning-debt.md<br/>deferred depth")]
    F -.real decision.-> J["write an ADR → <b>/adr-review</b>"]
    I -.pull in later.-> E

The loop is simple and you repeat it: get a guide → build → verify → log progress → next. Decisions become ADRs you own. Deep rabbit holes get scheduled, not skipped.

---

🎚️ The mode dial — the part everyone asks about

Most "learn by building" setups have one rigid rule: the AI never writes code. Great for retention, terrible for momentum. atelier makes it a dial you set per project and change anytime (just say "set mode to autopilot"):

Mode	Who writes the code	You optimize for	Pick it when…
🧗 guided (default)	You. AI writes guides + challenges only.	Deepest retention	The skill is your goal
🤝 collab	Both. AI does the boring parts; you build the core.	Balance	You want the hard 30%, not the tedium
🚀 autopilot	AI. You review & steer.	Maximum momentum	You want to ship and learn by reading

   retention ◀───────────────────────────────────▶ momentum
        guided          collab          autopilot

In autopilot, whenever the AI skips a deep dive to keep you moving, it logs it to learning-debt.md — so depth is deferred, not lost, and can come back later as a milestone or stretch challenge. Mix modes freely: autopilot the plumbing, guided the parts you came to master. → Full mode guide

---

Why it works

• 🧠 Progression beats perfection. Motivation is the scarce resource. Milestones are small and always end in something runnable. Momentum first; depth follows.
• 🕳️ Deferred depth, on purpose. Rabbit holes get written down and scheduled instead of stalling you or being forgotten.
• 🧭 You own the decisions. Architecture choices are written by you as ADRs; the AI lays out honest options and then challenges your reasoning. Owning decisions is most of what "senior" means.
• 🎓 Mentor, not autocomplete. Even in autopilot, every meaningful choice comes with a why and a 30-second review checklist.
• 📦 Idea-agnostic & stack-agnostic. No opinions about what you build or which tools — it adapts to you during onboarding.

→ Read the methodology

---

🧩 Works with your tools (no lock-in)

One canonical contract — AGENTS.md — drives every tool. The rest are thin pointers, so behavior is identical whether you're in Claude Code or Codex.

Tool	Reads	Commands
Claude Code	CLAUDE.md	.claude/skills/ → /start, /milestone, /progress, /mode, /adr-review, /lesson
Cursor	.cursor/rules/methodology.mdc	.cursor/commands/
GitHub Copilot (VS Code)	.github/copilot-instructions.md	ask by name
Gemini CLI	GEMINI.md	.gemini/commands/*.toml
OpenAI Codex	AGENTS.md	ask by name
Anything else	AGENTS.md	"run the milestone playbook"

No command system? Just say "run the milestone playbook" (or any name) and the agent reads the matching file in docs/playbooks/. That's the whole trick.

---

Anatomy of a build guide

Every build step is one self-contained milestone doc in the same six-part shape, so you always know what you're looking at:

1. Concept — why before how; the problem and how a senior thinks about it.
2. ADR — the decision this forces (options + trade-offs; you write the record).
3. Guided build — small annotated steps, each ending in something runnable.
4. Challenges — ~20–30% left for you, with escalating hints, no inline answers.
5. Verify — exact commands and the output you should see.
6. Stretch — optional depth and rabbit holes.

→ Milestone format · Template

---

📂 What's in the box

atelier/
├── README.md                     ← you are here
├── AGENTS.md                     ← canonical AI contract (every tool defers to this)
├── PROJECT.md                    ← your project's live state: name, mode, phase
├── CLAUDE.md · GEMINI.md         ← per-tool entrypoints → AGENTS.md
├── .github/copilot-instructions.md
├── .cursor/  .claude/  .gemini/  ← per-tool rules + command wrappers
└── docs/
    ├── methodology.md            ← the why behind it all
    ├── MODES.md                  ← the guided / collab / autopilot dial
    ├── CUSTOMIZE.md              ← set it up by hand (no-AI path)
    ├── progress.md               ← roadmap (phases→milestones) + session log
    ├── learning-debt.md          ← deferred deep dives
    ├── design/system-design.md   ← living source of truth for your project
    ├── adr/                      ← your decision log (+ template)
    ├── milestones/               ← build guides (+ six-part template)
    ├── tracks/                   ← optional deep-dive mini-courses
    └── playbooks/                ← the workflows your mentor runs

---

FAQ

Do I have to use Claude / Cursor / a specific tool?

No. Any agentic AI coding tool works — they all read AGENTS.md. The big ones get first-class command wrappers; everything else works by asking for a playbook by name.

What if I just want it to build my thing fast?

Set mode to autopilot during onboarding (or anytime after). The AI writes the code and teaches as it goes, logging anything it glosses over to learning-debt.md so you can circle back. You're never stuck on the "type it all yourself" rule unless you choose to be.

Is this tied to any particular kind of project?

No — it's deliberately idea-agnostic and stack-agnostic. Web app, CLI, game, data pipeline, embedded — onboarding adapts the roadmap and stack to whatever you're building.

Can I set it up without talking to an AI?

Yes. Follow docs/CUSTOMIZE.md for the manual checklist.

Why "atelier"?

An atelier is a workshop where you learn a craft by making real things under a master's eye — exactly the relationship this repo sets up between you and your AI mentor.

---