The Anatomy of Effective AI Instructions

What You'll Learn

Over the last two sections, you've built project memory, rules files, user preferences and configuration. It works. Claude follows your conventions, uses your tools, and writes code the way you expect.

But you built it instinctively. One rule here, another preference there, a command reference somewhere else. This lesson gives you a framework to understand why it works. You don't need to restructure anything. The goal is to recognise the pattern so you can use it intentionally going forward.

The Four-Part Framework

Every effective AI instruction set, whether it's a CLAUDE.md, an AGENTS.md, a Cursor rules file or a custom agent prompt, follows the same anatomy:

This isn't just theory. You've already built all four parts without realising it. Let's look at where each one lives in what you've created so far.

Mapping What You Built

Identity (Sections 3 + 4)

You've already written identity across two places, just not labelled as such.

Your user-level memory (~/.claude/info.md) tells Claude who you are: your name, your role, your experience level. Your project AGENTS.md tells Claude what the project is: tech stack, architecture, conventions. Together, they give Claude its identity for this context.

You might not have a single heading that says "Identity", but the information is there. Your AGENTS.md opens with tech stack details. Your info.md introduces you by name and role. Claude pieces these together to understand its context.

When you write new instructions in the future, consider leading with identity. Something as simple as this at the top of AGENTS.md makes a difference:

You are working on a Next.js 15 site using React 19, Tailwind CSS v4,
shadcn/ui and Framer Motion. The site is a personal portfolio and
course platform deployed on AWS Amplify.

One sentence that tells Claude the context before it reads a single rule.

Principles (Sections 3 + 4)

Your anti-patterns list from AGENTS.md? Those are principles. Your user preferences about "find the root cause, don't mask the problem"? Also principles.

Right now they're scattered across multiple files. That's fine. But now that you can see them as principles, you'll notice when you're writing one. In future projects, grouping them together makes your instructions easier to scan:

# Principles
 
- Server Components by default. Only add 'use client' when you need
  browser APIs
- Fix root causes. Don't add retry logic to mask a slow API
- Read before you write. Explore the codebase before making changes
- When in doubt, prefer the more restrictive option
- Never commit or push without confirming with me first

These aren't rules about a specific technology. They're how Claude should think when making decisions.

Domain Knowledge (Section 3)

This is the bulk of what you built in Section 3: your tech stack table, version constraints, file structure, naming conventions, Tailwind v4 configuration details.

# Domain Knowledge
 
## Technology Stack
| Technology | Version | Constraint |
|---|---|---|
| Next.js | 15.5.7 | Pinned - must match Bun's @next/swc |
| Tailwind CSS | 4.x | CSS-first config, NO tailwind.config.ts |
| Biome | 2.x | Linting + formatting, NOT ESLint |
 
## File Structure
- components/home/     # Landing page components
- components/course/   # Course-related components
- components/ui/       # shadcn primitives (editable source)
- lib/constants.ts     # Site content (single source of truth)

Domain Knowledge is factual. It doesn't tell Claude what to do. It tells Claude what's true about this project.

Workflow (Sections 3 + 4)

Your commands section and session completion checklist from AGENTS.md? That's workflow. It tells Claude how to approach tasks:

# Workflow
 
## Commands
- bun dev           # Dev server
- bun run lint      # Biome check + fix
- bun run type-check # TypeScript strict check
 
## Before Finishing Any Session
1. Run quality gates: bun run lint && bun run type-check
2. Update task status
3. Push to remote
4. Verify git status shows "up to date"

Workflow is procedural. It's the step-by-step process Claude follows when working.

Seeing the Pattern

Now look at your AGENTS.md through this lens:

# AGENTS.md (what you built)
## Technology Stack          ← Domain Knowledge
## Critical Implementation   ← mix of Principles + Domain Knowledge
## Anti-Patterns             ← Principles
## Commands                  ← Workflow
## Session Completion        ← Workflow

You didn't label the sections this way, but the content maps cleanly. The framework isn't something you need to restructure your files around. It's a way of seeing what you've already done, and being intentional about it when you add new instructions.

Why This Matters

This framework produces better code for a specific reason: it reduces ambiguity. When Claude encounters a decision point, like "should I use a Server Component or a Client Component here?", it has a clear path:

1. Identity tells it this is a Next.js 15 project (Server Components by default)
2. Principles say "Server Components by default, only add 'use client' when you need browser APIs"
3. Domain Knowledge confirms React 19 with the App Router
4. Workflow says to explore the code first before making changes

Without the framework, Claude might find the right answer eventually. With it, Claude finds it immediately and consistently.

This Framework Is Portable

The four-part anatomy isn't specific to Claude Code. It works with any AI coding tool:

The file names change. The framework doesn't. If you ever switch tools or use multiple tools on the same project, your instructions transfer directly.

What Comes Next

In the free preview, you've learned to configure one AI session: your project memory, your personal preferences, your reasoning controls. Everything runs in the main conversation.

In later sections, you'll see this same framework scale into more powerful patterns:

• Skills that trigger on-demand workflows with their own instructions
• Custom agents that work autonomously with their own Identity, Principles, Domain Knowledge and Workflow
• Hooks that validate Claude's work automatically before and after each action

The framework you learned here is the foundation for all of it.

Key Takeaways

• Effective AI instructions follow four parts: Identity, Principles, Domain Knowledge and Workflow
• You've already built all four parts across Sections 3 and 4. You don't need to restructure anything
• The framework is a lens for recognising what you've done and being intentional when you add new instructions
• Identity reduces generalist behaviour. Principles reduce ambiguity. Domain Knowledge prevents mistakes. Workflow creates consistency
• The framework is portable across Claude Code, Cursor, Copilot, Gemini CLI and Codex
• Later sections build on this same framework for skills, agents and automation

Checkpoint: This is the end of Section 4 and the free preview. The checkpoint/s5 branch has the project in this exact state.