You Shouldn't Use Claude Code Without This

Source: AI LABS | https://www.youtube.com/watch?v=ywIhw15za9Y Duration: 13 min | Published: 2026-04-10 Processed: 2026-04-10

Core Concepts

The 60 years of structured software engineering process (requirements, specs, tests, version control, staged rollout) are not obsolete under AI — they have been repurposed. They used to exist so humans could build reliably; now they exist so AI agents (autonomous code-writing processes driven by a model) can follow the same reliability rails humans did.
Environment setup before a single prompt is the determining factor in whether an agent produces useful output. Prompting quality matters far less than the surrounding scaffolding.
Planning split into two distinct layers:
- Product planning — what the app is for, who uses it, what the MVP (Minimum Viable Product — the smallest version that proves the idea works) contains. This should NOT be done by Claude Code's built-in plan mode, because plan mode is biased toward technical decomposition.
- Technical planning — architecture, scalability, failure modes. This IS what plan mode is good at and should be reserved for.
A dedicated planner agent (a subagent with its own system prompt and context) is used for product planning. It interrogates the user until requirements are clear, then writes a PRD (Product Requirements Document) into the project folder, divided into phased implementation chunks.
CLAUDE.md is the persistent instruction file loaded once into the agent's context and kept there for the whole session:
- It should contain only things the agent cannot figure out from reading the code itself (conventions, rules, tone, project principles).
- It should NOT contain structural information the agent can derive by reading files (directory layout, file contents).
- It should link to the PRD rather than duplicate its contents.
- It is a living file — keep appending to it as the project reveals what the agent needs told explicitly.
- The auto-generated version from /init is weaker because it describes what currently exists, not what the agent needs to know going forward. Write it by hand.
Skills vs agents — the distinction matters because they serve different structural purposes:
- Skills = repeatable workflows with references, scripts, and guidelines the agent loads on demand. Example: a front-end skill that enforces component conventions every time UI work happens.
- Agents = isolated contexts for specific jobs that benefit from clean state. Example: a commit agent, a refactor agent, a UI-verification agent using Playwright MCP (a browser-automation bridge).
- Rule: if the task is repeatable and needs guidance, it's a skill. If the task needs its own clean context window, it's an agent.
MCPs (Model Context Protocol servers — standardised bridges that let agents call external services) should be wired up before the build starts, not mid-flight. Examples from the video: Supabase MCP for backend, shadcn/ui integration for components, Playwright MCP for browser testing.
Path-specific rules — instruction files scoped to particular folders of the codebase. CLAUDE.md is for broad principles that apply everywhere; path-specific rules tell the agent what to do inside one area (e.g. src/auth/ has different conventions than src/ui/). They should be linked from CLAUDE.md so the agent knows to look for them.
Negative constraints close a gap positive specs leave open:
- Agents are biased toward action and will invent behaviour beyond what the positive spec says.
- A dedicated "what NOT to do" file in the docs folder, linked from CLAUDE.md, removes that ambiguity.
- Concrete example: explicitly state "do not use the default purple/blue/white palette" rather than just describing what you want.
Two files that every project setup must have to keep the agent honest over long builds:
- Progress file — a single place the agent reads to know what's been done and what's still pending. Without this, the agent has to re-read implementation code and cross-reference docs every cycle, which wastes tokens and compounds drift.
- Learnings file — a log of errors encountered, root causes, and fixes. Lets the agent avoid repeating the same mistakes in later work.
- Both must be explicitly instructed-on in CLAUDE.md so the agent actually updates them while building.
Tests written first, derived from the PRD — not the implementation. Reason:
- If tests are written after the code, the agent knows only what was built and writes tests that confirm current behaviour — including bugs and missing features.
- If tests are derived from the PRD, they test what the spec required, which surfaces implementation gaps.
- "Test the application" is an open-ended prompt and gets you tests that optimise toward whatever the agent already did. Tie tests to specs explicitly.
Issue tracking set up from day one — not when things start breaking:
- GitHub issues + structured commit messages give the agent a historical record it can read to understand project evolution and revert cleanly.
- Git worktrees (parallel working directories tied to different branches) allow experimental work in isolation without touching the main branch.
- For non-technical collaborators, connect a project-management MCP (Trello, Notion) so bugs can be filed without touching git. Instruct CLAUDE.md to use that MCP for bug tracking.
Load testing and concurrency planning must happen before production:
- AI-generated code is typically written as if a single user will hit it. It is not inherently concurrency-safe.
- Tell the agent the expected number of simultaneous users upfront; have it write stress tests (the video used K6, a load-testing tool for HTTP endpoints).
- For this phase, plan mode IS the right tool — it maps multiple technical approaches based on concurrency assumptions and surfaces production failure modes before they happen.

Buildable Ideas

Planner agent as a reusable Himiko skill — asks interview questions, produces a PRD in a standard template, saves to the active project folder. Generalises across any new build.
CLAUDE.md linter — a tool that audits a project's CLAUDE.md and flags content the agent could derive from the filesystem (bloat) vs. content that genuinely needs telling (signal).
Negative-constraints template — a reusable docs/negative-constraints.md starter that every new project inherits, pre-populated with the class of mistakes agents commonly make (invented dependencies, default palettes, unwanted file creation, cleanup sweeps beyond scope).
Progress + learnings file pair as a standard scaffold — auto-generated at project init, linked from CLAUDE.md, with clear update instructions. Every WAT-framework project Himiko touches could adopt this.
Spec-first test skill — a skill that reads the PRD and generates Playwright or Jest test stubs from the requirements, before any implementation happens. Enforces the "tests derived from spec, not code" discipline.
Stress-test preflight agent — takes a near-complete project, extracts expected concurrency from the PRD, writes and runs K6 load tests, reports failure thresholds. Runs before every production deploy.
Modular progression — planner → CLAUDE.md writer → negative-constraints seeder → progress/learnings scaffolder → test-first generator → stress-test preflight. Each module is independent but together they form a production-readiness pipeline for any Claude Code build.

Key Takeaways

The work that decides whether an AI build succeeds happens before the first prompt: product planning, PRD, CLAUDE.md, skills, agents, MCPs, constraints, progress/learnings files. Skipping setup to "just start" is the dominant failure mode.
CLAUDE.md is load-once, persist-forever — treat every line as context budget and only write things the agent cannot derive itself.
Skills vs agents is a clean split: repeatable guidance = skill, isolated job context = agent. Use both; don't conflate them.
Negative constraints are as important as positive specs. Tell the agent what not to do, in writing, linked from CLAUDE.md.
Tests from the PRD catch gaps. Tests from the implementation only ever confirm what was built. Write them first.
Production readiness is a pre-planned phase, not an afterthought. Concurrency, load, and failure modes need their own technical plan before deploy — this is where Claude Code's plan mode actually earns its keep.

# You Shouldn't Use Claude Code Without This **Source:** AI LABS | https://www.youtube.com/watch?v=ywIhw15za9Y **Duration:** 13 min | **Published:** 2026-04-10 **Processed:** 2026-04-10 --- ## Core Concepts - The 60 years of structured software engineering process (requirements, specs, tests, version control, staged rollout) are not obsolete under AI — they have been repurposed. They used to exist so humans could build reliably; now they exist so **AI agents** (autonomous code-writing processes driven by a model) can follow the same reliability rails humans did. - Environment setup before a single prompt is the determining factor in whether an agent produces useful output. Prompting quality matters far less than the surrounding scaffolding. - Planning split into two distinct layers: - **Product planning** — what the app is for, who uses it, what the MVP (Minimum Viable Product — the smallest version that proves the idea works) contains. This should NOT be done by Claude Code's built-in plan mode, because plan mode is biased toward technical decomposition. - **Technical planning** — architecture, scalability, failure modes. This IS what plan mode is good at and should be reserved for. - A dedicated **planner agent** (a subagent with its own system prompt and context) is used for product planning. It interrogates the user until requirements are clear, then writes a **PRD** (Product Requirements Document) into the project folder, divided into phased implementation chunks. - **CLAUDE.md** is the persistent instruction file loaded once into the agent's context and kept there for the whole session: - It should contain only things the agent cannot figure out from reading the code itself (conventions, rules, tone, project principles). - It should NOT contain structural information the agent can derive by reading files (directory layout, file contents). - It should link to the PRD rather than duplicate its contents. - It is a living file — keep appending to it as the project reveals what the agent needs told explicitly. - The auto-generated version from `/init` is weaker because it describes what currently exists, not what the agent needs to know going forward. Write it by hand. - **Skills vs agents** — the distinction matters because they serve different structural purposes: - **Skills** = repeatable workflows with references, scripts, and guidelines the agent loads on demand. Example: a front-end skill that enforces component conventions every time UI work happens. - **Agents** = isolated contexts for specific jobs that benefit from clean state. Example: a commit agent, a refactor agent, a UI-verification agent using Playwright MCP (a browser-automation bridge). - Rule: if the task is repeatable and needs guidance, it's a skill. If the task needs its own clean context window, it's an agent. - **MCPs** (Model Context Protocol servers — standardised bridges that let agents call external services) should be wired up before the build starts, not mid-flight. Examples from the video: Supabase MCP for backend, shadcn/ui integration for components, Playwright MCP for browser testing. - **Path-specific rules** — instruction files scoped to particular folders of the codebase. CLAUDE.md is for broad principles that apply everywhere; path-specific rules tell the agent what to do inside one area (e.g. `src/auth/` has different conventions than `src/ui/`). They should be linked from CLAUDE.md so the agent knows to look for them. - **Negative constraints** close a gap positive specs leave open: - Agents are biased toward action and will invent behaviour beyond what the positive spec says. - A dedicated "what NOT to do" file in the docs folder, linked from CLAUDE.md, removes that ambiguity. - Concrete example: explicitly state "do not use the default purple/blue/white palette" rather than just describing what you want. - Two files that every project setup must have to keep the agent honest over long builds: - **Progress file** — a single place the agent reads to know what's been done and what's still pending. Without this, the agent has to re-read implementation code and cross-reference docs every cycle, which wastes tokens and compounds drift. - **Learnings file** — a log of errors encountered, root causes, and fixes. Lets the agent avoid repeating the same mistakes in later work. - Both must be explicitly instructed-on in CLAUDE.md so the agent actually updates them while building. - **Tests written first, derived from the PRD — not the implementation.** Reason: - If tests are written after the code, the agent knows only what was built and writes tests that confirm current behaviour — including bugs and missing features. - If tests are derived from the PRD, they test what the spec *required*, which surfaces implementation gaps. - "Test the application" is an open-ended prompt and gets you tests that optimise toward whatever the agent already did. Tie tests to specs explicitly. - **Issue tracking set up from day one** — not when things start breaking: - GitHub issues + structured commit messages give the agent a historical record it can read to understand project evolution and revert cleanly. - Git worktrees (parallel working directories tied to different branches) allow experimental work in isolation without touching the main branch. - For non-technical collaborators, connect a project-management MCP (Trello, Notion) so bugs can be filed without touching git. Instruct CLAUDE.md to use that MCP for bug tracking. - **Load testing and concurrency planning** must happen before production: - AI-generated code is typically written as if a single user will hit it. It is not inherently concurrency-safe. - Tell the agent the expected number of simultaneous users upfront; have it write stress tests (the video used K6, a load-testing tool for HTTP endpoints). - For this phase, plan mode IS the right tool — it maps multiple technical approaches based on concurrency assumptions and surfaces production failure modes before they happen. ## Buildable Ideas - **Planner agent** as a reusable Himiko skill — asks interview questions, produces a PRD in a standard template, saves to the active project folder. Generalises across any new build. - **CLAUDE.md linter** — a tool that audits a project's CLAUDE.md and flags content the agent could derive from the filesystem (bloat) vs. content that genuinely needs telling (signal). - **Negative-constraints template** — a reusable `docs/negative-constraints.md` starter that every new project inherits, pre-populated with the class of mistakes agents commonly make (invented dependencies, default palettes, unwanted file creation, cleanup sweeps beyond scope). - **Progress + learnings file pair** as a standard scaffold — auto-generated at project init, linked from CLAUDE.md, with clear update instructions. Every WAT-framework project Himiko touches could adopt this. - **Spec-first test skill** — a skill that reads the PRD and generates Playwright or Jest test stubs from the requirements, before any implementation happens. Enforces the "tests derived from spec, not code" discipline. - **Stress-test preflight agent** — takes a near-complete project, extracts expected concurrency from the PRD, writes and runs K6 load tests, reports failure thresholds. Runs before every production deploy. - **Modular progression** — planner → CLAUDE.md writer → negative-constraints seeder → progress/learnings scaffolder → test-first generator → stress-test preflight. Each module is independent but together they form a production-readiness pipeline for any Claude Code build. ## Key Takeaways - The work that decides whether an AI build succeeds happens **before** the first prompt: product planning, PRD, CLAUDE.md, skills, agents, MCPs, constraints, progress/learnings files. Skipping setup to "just start" is the dominant failure mode. - CLAUDE.md is load-once, persist-forever — treat every line as context budget and only write things the agent cannot derive itself. - Skills vs agents is a clean split: repeatable guidance = skill, isolated job context = agent. Use both; don't conflate them. - Negative constraints are as important as positive specs. Tell the agent what not to do, in writing, linked from CLAUDE.md. - Tests from the PRD catch gaps. Tests from the implementation only ever confirm what was built. Write them first. - Production readiness is a pre-planned phase, not an afterthought. Concurrency, load, and failure modes need their own technical plan before deploy — this is where Claude Code's plan mode actually earns its keep.