How I document my AI-first workflow in every public repo

TL;DR

In every one of my public repos I keep three artifacts that make my AI-first workflow visible from the file tree, not just claimed in a README:

1. CLAUDE.md — a literal table of "who did what" (human vs AI) per layer of the project, plus a list of things I rejected from the AI's draft, plus "known gotchas for the next AI pass."
2. .claude/commands/ — one slash command per repo, tuned to the most expensive failure mode (security review, math invariants, WebGL disposal, hook chain audit, React contract).
3. For one representative repo — a full CASE_STUDY.md: 90-minute build retrospective, step by step, threat model → SDK lookup → AI draft → line-by-line audit → hardening → in-browser verification → docs.

Decision authority (architecture, security posture, API contract, cost engineering, what to reject) stays with the human. AI gets boilerplate and first drafts. This post shows the how, with links to five working repos as reference.

---

Why publish this at all

Because AI-augmented work isn't worth hiding. Developers who cover it up today will be the ones saying "I don't do computers" in two years. Companies hiring devs already write "AI-first (Claude, Copilot, Cursor)" straight into job posts — and they want to see evidence, not statements.

But "evidence of AI-first work" isn't "I have ChatGPT open in a tab." It's artifacts in the file tree. This post shows three concrete ones I've deployed across every public repo I own.

Artifact 1: CLAUDE.md with a human/AI split

CLAUDE.md is the file Claude Code reads as project context (analogous to .cursorrules or AGENTS.md). But I use it for two audiences at once:

1. For the next AI pass — so the model knows what's sacred and what's flexible in this repo.
2. For humans — so anyone browsing the file tree (a client, a recruiter, a teammate) sees, in black and white: who did what.

The table shape I use in every repo:

Layer	Who did it	Why
Threat model & architecture (proxy, not client-side call)	Human	The whole reason this repo exists. Delegating "should the API key touch the browser?" to an AI is how you ship a leaked-key incident. Not negotiable.
Server-side proxy skeleton	AI-drafted, human-reviewed line by line	Claude wrote the first pass; I audited every line for four things: (1) key never in response headers or logs, (2) role validated, not trusted, (3) input length capped, (4) SSE framing correct.
Widget UI (vanilla JS, ~6 KB)	AI-drafted, human-styled	Dependency-free was a hard constraint from me. textContent (not innerHTML) on user text is mine — XSS prevention isn't a call to leave to the model's discretion.
Prompt caching decision	Human	Cost engineering — the difference between $10/mo and $1/mo of API spend.

Three things make this useful and not fluff:

• The "Why" column is the part most people skip. It's also the only place you can tell the author understood why they delegated (or didn't).

• A "What I rejected from the AI's draft" section — I write out, in plain text, what Claude proposed, what I refused to merge, and why. This is what separates "I use AI" from "I use AI well." An example from one of my repos:

Rejected two things Claude proposed initially:
(1) logging the request body — would log user PII to a plain file. Removed.
(2) falling back to $_ENV['ANTHROPIC_API_KEY'] if getenv() returned false — unnecessary, and on some hosting stacks it could pick up stale values. Removed.

• A "Known gotchas for the next AI pass" section — spots where the next iteration of AI would do something dumb. This protects both me and the model — because Claude reads this file as context, so the next round it won't re-propose an idea that's already been rejected.

Working examples:
CLAUDE.md in claude-chat-widget ·
claude-chat-react ·
booking-slots-php ·
woocommerce-custom-product-data ·
threejs-product-configurator-starter.

Artifact 2: A case study — one build, step by step

CLAUDE.md tells you what someone did. A case study tells you how and in what order. Two different documents, both needed.

The case study I wrote for claude-chat-widget has eight sections, each one concrete step of a 90-minute build:

1. Threat model and architecture (human, before writing a single line of code)
2. Looking up the exact SDK shape (human, from the claude-api skill) — because the model's training data may be stale for SDK APIs
3. AI drafts the proxy skeleton (Claude, ~10 min)
4. Line-by-line audit + hardening (human, ~20 min) — the most important section
5. AI drafts the widget (Claude, ~10 min)
6. Widget audit + hardening (human, ~15 min) — XSS, dark mode, mobile, UX
7. Verification in a real browser (human, ~10 min)
8. Documentation (human, ~15 min) — because LLMs write generic READMEs

This format has one unexpected side effect: it forces honesty. When you write "AI wrote 60% of the lines, human made every load-bearing decision" — you have to say which decisions those were. Suddenly it's visible where you actually did the work, versus where you just signed off on a generated file.

Full case study: CASE_STUDY.md.

Artifact 3: .claude/commands/ — automating the review

Claude Code (and most agents) support slash commands — Markdown files under .claude/commands/ invoked in a session as /name. They load as part of the prompt, so I can save a checklist and pull it up with one word.

Every repo I own has one such file, tuned to the class of failure I most want to catch:

• security-review.md (claude-chat-widget) — 6-invariant audit of the proxy's security posture (key only in Anthropic\Client(apiKey:), role validated, length capped, X-Accel-Buffering: no, etc.). Runs before every merge to server/chat.php.
• react-security-review.md (claude-chat-react) — 8-invariant audit for the React version (no @anthropic-ai/sdk import in src/, no dangerouslySetInnerHTML, setMessages(prev => ...) never closure-based, AbortController in a ref not state, react in peerDependencies, a11y attributes preserved).
• verify-slot-math.md (booking-slots-php) — audit of the overlap math (half-open intervals [start, end), < not <=, symmetric buffer). Because booking bugs come from off-by-one errors right there.
• hook-audit.md (woocommerce-custom-product-data) — audit of the three-hook WooCommerce chain.
• webgl-review.md (threejs-product-configurator-starter) — geometry disposal (so WebGL doesn't leak) and "no build step" invariant (so nobody sneaks Vite in).

The effect: repeatable code review that doesn't depend on my discipline on a given day. Instead of remembering all six points every time I touch the proxy, I type /security-review and get the checklist.

Why these three artifacts

Because they cover the three levels of question anyone evaluating your AI-first work actually asks:

Question	The artifact that answers it
"What specifically did you do vs the AI?"	CLAUDE.md — one-screen table
"What does your process look like — order of decisions, what you reject from AI drafts?"	CASE_STUDY.md — one build retrospective
"Can you configure agents, or do you just type in a chat?"	.claude/commands/ — config tuned to a specific failure class

A recruiter reviewing 40 GitHub profiles a week isn't going to read your code. They are going to scan your file tree. If they see CLAUDE.md, CASE_STUDY.md, and .claude/commands/ there — they immediately know they're looking at someone who actually practices the workflow, not someone who put it in their CV.

The philosophy I'm trying to make routine

AI is a fast typist and a reasonable reviewer. Decision authority — architecture, threat model, validation strategy, dependency selection, what to reject — stays with the human. When I hand decision authority to a model, I get a repo that lints clean and blows up in production.

This philosophy works well enough that I shipped 5 working public repos (a WordPress plugin, a PHP booking-slots engine, a Three.js configurator starter, a vanilla-JS chat widget, and a React chat widget on Claude API) — each with a full CLAUDE.md, docs, badges, and a pinned v1.0.0 release. Every load-bearing decision documented, every AI draft audited before merge.

Full profile: github.com/GronskiDeveloper. Fork any repo and check what CLAUDE.md looks like in practice.

---

I build websites, e-commerce, custom 3D configurators and AI assistants — see grodev.pl or grodev.pl/ai. Poznań, Poland, remote across PL and EU.