Claude Code for Non-Coders

The complete method a non-developer uses to build a real application with
Claude Code — without being able to read the code it writes.

This repo is not a collection of prompt tips. It's a governance system:
how to decide, verify, constrain, and sustain a software project when you
can't personally review what the AI produces. Everything here was forged on a
real project — a family mobile app (React Native + Firebase, some thirty
server functions, security rules tested in continuous integration) — by
someone whose job is not software development.

Every rule in this repo was born from a real accident. These are scars, with
the user manual attached.

One-sentence install

Paste this into Claude Code:

"Read https://raw.githubusercontent.com/Arlenjim/claude-code-for-non-coders/main/INSTALL.md
and follow its instructions."

Claude becomes your private technical installer: you hand it the keys to
the site, it puts up its own scaffolding. It installs the skills, asks you
three questions to fit the method to YOUR project, and explains every piece
as it lays it down. Nothing is overwritten without your consent, no guardrail
is imposed. (Manual install: see "Where to start" below.)

🇫🇷 Ce dépôt est né en français — voir README.fr.md.

The story in three acts

Act 1 — over-armoring. At first, the fear of not being able to verify the
code produced a pile of guardrails: six automatic blocking hooks, a mandatory
planning process for the smallest edit, isolated environments, numbered
rituals. The result: lots of friction, false positives, and the real risk —
errors of judgment — slipped through anyway.

Act 2 — "lighten, don't harden." An external audit and a few incidents
led to this method's central decision: we removed four hooks out of six,
made the heavyweight process optional, and moved trust to the only barriers
that deserve it — tests replayed automatically by CI. A general-contractor
process is absurd for changing a light bulb.

Act 3 — balance. Few barriers, but the right ones, on the right tier:
discipline rules that are always loaded, method skills you can invoke, a
written doctrine for the critical domain, deterministic tests in CI, and a
session ritual that lets a memoryless AI pick the work back up cold.

What's in this repo

INSTALL.md              The install instructions — written for Claude,
                        not for you (see "One-sentence install")
CLAUDE-global.md        The rules file loaded into ALL your sessions
                        (copy to ~/.claude/CLAUDE.md and adapt)
skills/                 3 generic method skills, ready to copy
                        into ~/.claude/skills/
  work-discipline/          decompose, prove, refuse shortcuts
  scientific-debugging/     reproduce, bisect, prove the cause
  framing-vague-requests/   turn a vague request into executable work
templates/              The files to create in every long-lived project
  SESSION-HANDOFF.md        the handoff journal between sessions
  CLAUDE-project.md         the minimal project CLAUDE.md (incl. the
                            "non-negotiable domain")
  PROJECT-RESUME.txt        the ready-to-paste session opener
guardrails/             The 6 defense patterns + what we removed and why
  hooks-templates/          2 generic fill-in-the-blanks hooks, ready to wire
field-notes/            The method confronted with the wild — viral tips,
                        incidents, hard questions, and what we keep from them

Where to start (manual install)

The automatic path is above ("One-sentence install"). If you'd rather lay
everything down yourself:

1. Copy CLAUDE-global.md to ~/.claude/CLAUDE.md (create the folder if
   needed) and replace the <...> fields: your first name, your technical
   level, your paths.
2. Copy the three folders from skills/ into ~/.claude/skills/.
3. On your first long-lived project, ask Claude to initialize the setup
   (the "Bootstrapping" section of CLAUDE-global): it will create the
   handoff, the project CLAUDE.md, and the resume template.
4. Read guardrails/README.md before adding any automatic guardrail. The
   classic mistake is adding too many, not too few.

The five principles that carry everything

1. Front-loading: the pilot's effort is spent BEFORE the work (precise
   brief, written constraints, chosen execution mode), not during it. A fuzzy
   brief costs more than any AI mistake.
2. Asking ≠ announcing: an AI announcing what it's about to do has not
   asked permission. Any scope extension requires a question and an answer.
   And a flagged problem = full stop ("flag then STOP") — no coding in the
   same breath.
3. The non-negotiable domain: every project has a zone where a mistake is
   expensive (money, data, security). You define it in writing and apply a
   reinforced protocol there — everywhere else, you lighten up.
4. The guardrail hierarchy: tests replayed in CI (deterministic) >
   specialized review (probabilistic) > regex hooks (cosmetic). Place your
   trust on the highest tier available, never in a lint.
5. Proof, not narrative: "it should work" is not verification; an agent's
   report is not proof; a stale doc map is worse than no map. Everything gets
   verified observably.

Who this is for

This repo doesn't teach you to code: it teaches you to act as a technical
director in front of a team of virtual developers. It's for anyone driving
Claude Code (or an equivalent tool) on a project that matters, without
being able to read the code in depth: non-technical founders, designers,
product managers, side-project artisans. Developers will find plenty here
too — half of these rules are simply good engineering, written to be demanded
rather than performed.

What this repo is not

• A service. It's an artifact published as is; no support promised, no
  roadmap. Issues and PRs are welcome but come with no guarantee of a reply.
• A guarantee. This method drastically reduces the damage; it replaces
  neither a security audit nor a developer for the stakes that require one.
• Dogma. The method itself was cut down once ("lighten, don't harden").
  Take what serves you, discard the rest — but discard knowingly: every piece
  documents the problem it solves.

License

MIT — see LICENSE. Do what you want with it; a mention is
appreciated, not required.