study-buddy

An instruction set for AI coding tools that puts a beginner software engineering student in the driver's seat instead of the passenger seat.

Most AI coding assistants default to writing the solution the moment you describe a task. That's great for shipping code, and terrible for learning to code. study-buddy flips the default: plan first, explain fundamentals with plain analogies, hint before handing over answers — and only writes code directly for scaffolding, tooling breakage, or when you explicitly ask for a reference build.

Read the full philosophy in core/study-buddy.md — that file is the single source of truth; every tool-specific file below is generated from it.

Install

npx @astathedev/study-buddy

You'll be asked which tool(s) you use and where to install:

| Tool | File written | |---|---| | Claude Code | .claude/skills/study-buddy/SKILL.md (project) or ~/.claude/skills/study-buddy/SKILL.md (personal, all projects) | | Cursor | .cursor/rules/study-buddy.mdc | | Codex / any AGENTS.md-reading tool | AGENTS.md at the project root | | GitHub Copilot | .github/copilot-instructions.md |

AGENTS.md and copilot-instructions.md are instruction files other tooling may already use, so study-buddy inserts its content between <!-- study-buddy:start --> / <!-- study-buddy:end --> markers instead of overwriting the file. Re-running the installer updates just that block.

Re-run npx @astathedev/study-buddy any time to pick up updates.

Manual install

Prefer not to run the installer? Copy the relevant file from adapters/ straight to the destination in the table above.

How it behaves

• Plans before coding. Breaks a task into steps and names the underlying fundamentals before any syntax appears.
• Explains with physical analogies ("caveman" style) — a variable is a labeled box, a loop is a chore repeated until told to stop — before introducing the technical term.
• Hints instead of solving, escalating gradually: a nudge, a concept reminder, an adjacent example, a skeleton, and only as a last resort a small annotated snippet.
• Still writes code when it should — project scaffolding, broken tooling, or an explicit "just build it, I'll study the reference" request. It says which exception applies rather than quietly defaulting to agent mode.

See core/study-buddy.md for the complete instructions.

Repo layout

core/study-buddy.md         canonical instructions (edit this)
adapters/claude/SKILL.md    generated: Claude Code skill
adapters/cursor/*.mdc       generated: Cursor rule
adapters/codex/AGENTS.md    generated: Codex / AGENTS.md convention
adapters/copilot/*.md       generated: GitHub Copilot instructions
scripts/build.js            regenerates adapters/ from core/study-buddy.md
bin/cli.js                  the `npx @astathedev/study-buddy` installer

Contributing

Edit core/study-buddy.md, then regenerate the adapters:

npm run build

Don't hand-edit files under adapters/ — they're overwritten on the next build.

License

MIT