Claude Code – Claude.md & Plan Mode (Quick Revision)¶

1. Claude.md¶

• A project instruction file that gives Claude context about your codebase.
• Created using:

claude init

• Claude scans your project and generates a Claude.md.

2. What Claude.md Contains¶

• Project overview
• Tech stack
• Commands (npm, bun, etc.)
• Architecture
• Folder structure
• State management
• Data flow
• Coding conventions

Benefit: Claude understands your project better and needs fewer exploratory tool calls.

3. When to Add Information¶

Rule:

If you keep repeating the same instruction in prompts, put it in Claude.md.

Examples:

• Coding standards
• Preferred libraries
• Project conventions
• Build/test commands

4. Keep It Small¶

• Claude.md is added to every prompt.
• Larger files consume more context tokens.
• Remove unnecessary information to save context and usage.

5. Context Window¶

Check current context usage with:

/context

Shows:

• Total tokens used
• System prompt usage
• Conversation history
• Plugins/Skills usage

6. Plan Mode¶

Before coding, ask Claude to create a plan.

Example:

Don't code anything yet.
Create an implementation plan first.

(or enable Plan Mode with Shift + Tab)

Benefit: Review the approach before any code changes.

7. Verification Loop¶

Always give Claude something to verify against:

• Screenshot
• Mockup
• Design
• Tests
• Requirements

Example:

Implement this UI.
Don't code yet.
First explain your implementation plan.

Claude compares the screenshot/design and identifies:

• New components
• API changes
• State changes
• New functionality

8. Claude.md Hierarchy¶

Claude uses the nearest Claude.md.

User Claude.md
      ↓
Repository Claude.md
      ↓
Subproject Claude.md

The closest file to your current working directory takes precedence.

Useful for monorepos, where each package can have its own Claude.md.

9. Best Practices¶

• Run claude init for every project.
• Keep Claude.md concise.
• Store repeated instructions in Claude.md.
• Use Plan Mode before implementation.
• Review Claude's plan like you would review a coworker's proposal.
• Use screenshots or tests as verification before coding.

Quick Interview/Revision Points¶

• claude init → Generates Claude.md.
• Claude.md → Persistent project context.
• /context → Shows token/context usage.
• Plan Mode → Plan first, code later.
• Verification Loop → Compare against screenshots, tests, or requirements.
• Monorepos → Nearest Claude.md is used.

/////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

Claude Code Permissions & Plan Mode – Revision Notes¶

1. Plan Mode¶

• Purpose: Lets Claude think and plan without making any code changes.
• No files are edited.
• No commands are executed.

• Useful for:

• Reviewing architecture

• Planning implementation
• Understanding codebase
• Designing solutions before coding

Think of Plan Mode as "permission to think, not permission to act."

2. Tool Calls¶

Claude itself doesn't directly execute commands.

Workflow:

User Prompt
      ↓
Claude decides a tool call
      ↓
Harness checks permissions
      ↓
Allowed?
   ↓        ↓
 Yes        No
Execute   Block/Ask

The permission system controls what actually runs.

3. Permission Types¶

There are three permission levels.

Allow¶

Runs automatically.

Example:

npm run
bun run

No confirmation required.

Ask¶

Claude asks before executing.

Example:

rm
git commit

Good for commands that modify files.

Deny¶

Claude can never execute it.

Example:

git push
edit package.json

Even if Claude wants to perform the action, it is blocked.

4. Allow List¶

Commands you trust.

Example

Allow:
- npm run
- bun run typecheck
- npm test

These execute without prompts.

5. Ask List¶

Commands requiring confirmation.

Example

Ask:
- rm
- mv
- git commit

Safer than Allow.

6. Deny List¶

Commands that must never run.

Example

Deny:
- git push
- edit package.json

Claude simply refuses.

Example:

User:
Update package.json

↓

Claude:
I can't do that because permissions deny editing package.json.

7. Default Permission¶

You can configure a default behaviour.

Example

default = ask

Any unknown command will request confirmation.

8. Managing Permissions¶

Instead of manually editing:

.claude/settings.json

Use the built-in command:

/permissions

It provides a UI to:

• Add rules
• Remove rules
• View current rules
• Manage permissions easily

9. Fewer Permission Prompts¶

New feature.

Command:

/fewer-permission-prompts

It analyses your previous Claude sessions.

If it notices:

You always allow:

bun run typecheck
Linear MCP server

it suggests adding them permanently to the Allow list.

Benefits:

• Fewer repetitive prompts
• Faster workflow

It is conservative:

• Doesn't add risky permissions
• Skips unsafe or redundant commands

Rule of thumb: When in doubt, leave it out.

10. Permission Hierarchy¶

Permissions exist at multiple levels.

Priority:

Enterprise Managed Settings
        ↓
Global Settings
        ↓
User Settings
        ↓
Project Settings

Higher levels override lower levels.

Example:

Company:

Deny git push

Project:

Allow git push

Result:

Denied

Enterprise policy wins.

11. Global vs Project Settings¶

Global¶

Applies to every project.

Example:

Always allow:

npm run

Works everywhere.

Project¶

Only affects the current repository.

Example:

Allow:
docker compose up

Only for that project.

12. Managed Settings (Enterprise)¶

Organisations can enforce permissions centrally.

Example:

Company blocks:

git push
rm -rf

Individual developers cannot override these restrictions.

13. Testing Permissions¶

Example:

Permission:

Deny:
edit package.json

Prompt:

Update package.json version

Result:

Claude:
I can't do that because permissions deny it.

Even if the model wants to edit the file, the permission system blocks execution.

14. Choosing Models¶

Sonnet¶

• Faster
• Cheaper
• Good default choice

Opus¶

• More capable
• More expensive
• Higher usage limits consumed

Recommended workflow:

Start with Sonnet
        ↓
If it struggles
        ↓
Switch to Opus

Using Opus by default may waste quota if Sonnet could handle the task.

15. Key Takeaways¶

• Plan Mode = analyse and plan without making changes.
• Claude proposes actions, but the permission system decides whether they execute.

• Three permission levels:

• Allow → execute automatically

• Ask → request confirmation
• Deny → never execute
• Use /permissions to manage rules instead of editing JSON manually.
• Use /fewer-permission-prompts to automatically reduce repetitive approval requests.
• Permission precedence is:

Enterprise
   ↓
Global
   ↓
User
   ↓
Project

• If rules conflict, the highest-level rule wins.
• Start with Sonnet and switch to Opus only when needed for complex tasks.

//////////////////////////////////////////////////////////////////////////////////////////////////////////////

Claude Code – Advisor, Effort & Context (Quick Revision)¶

1. Advisor Mode¶

• Lets you use another model for planning without switching your current model.

• Example:

• Sonnet → Implementation

• Opus → Planning (via Advisor)

Use case: Get a high-quality implementation plan from Opus while staying on Sonnet for coding.

2. Model vs Effort¶

Model¶

Determines the model's capability.

• Haiku → Fastest, simplest tasks
• Sonnet → Best default for most coding
• Opus → Complex reasoning and planning

Effort¶

Determines how deeply the model thinks.

Levels:

• Low
• Medium
• High
• Max

Model = Intelligence Effort = Thinking time

3. When to Increase Effort¶

If Claude:

• Gives incomplete answers
• Says "can't do that"
• Misses obvious steps

➡️ Try increasing Effort before switching to Opus.

4. Cost Consideration¶

Higher effort means:

• More reasoning
• Higher token usage
• Higher cost

Don't use Max for simple tasks (e.g., changing a button colour).

5. Context Window¶

View usage with:

/context

Modern models support up to 1 million tokens, but more isn't always better.

6. Large Context Issues¶

Very large conversations (300k–400k+ tokens):

• Reduce response quality
• Make it harder for the model to focus
• Can cost more when resuming old chats

Best practice: Start a new session or compact the conversation when it becomes very large.

7. Prompt Caching¶

Claude doesn't reread the entire conversation every time.

Instead:

• Previous conversation is cached.
• Only new messages are processed.

This improves speed and reduces token computation.

8. Best Practices¶

• Haiku → Quick/simple tasks.
• Sonnet → Daily coding (recommended default).
• Opus → Complex planning and reasoning.
• Use Advisor instead of switching models for planning.
• Increase Effort before upgrading the model.
• Keep conversations reasonably small (around 300k–400k tokens).
• Start a fresh session when context becomes cluttered.

Quick Revision¶

• Advisor → Use another model (e.g., Opus) for planning.
• Model = Capability.
• Effort = Amount of reasoning.
• Higher Effort = Better reasoning + higher cost.
• /context → View context/token usage.
• Prompt caching → Claude processes only new messages, not the entire history each time.
• Large contexts can reduce response quality; don't keep one session forever.

////////////////////////////////////////////////////////////////////////////////////////////////

Claude Code Skills – Quick Revision¶

1. What are Skills?¶

• Skills are reusable workflows stored as Markdown files.
• They automate tasks you'd otherwise explain repeatedly.

Examples:

• Code review
• Deployment
• Q&A workflow
• Integrations
• Bug analysis

Think of Skills as reusable prompts with instructions.

2. Creating a Skill¶

Structure:

skills/
└── code-reviewer/
    └── skill.md

You can use the built-in Skill Creator or create it manually.

3. Skill Contents¶

A skill contains:

• Name
• Description
• Step-by-step instructions

The description helps Claude decide when to use the skill.

4. How Skills Are Loaded¶

• Name + Description → Always included in the prompt.
• Full skill instructions → Loaded only when the skill is used.

Benefit: Saves context tokens.

5. Using Skills¶

Explicitly¶

/code-reviewer

Automatically¶

Claude can invoke a skill if your prompt matches its description.

Example:

Review this codebase.

Claude may automatically choose the code-reviewer skill.

6. Reload After Changes¶

After creating or editing a skill:

/reload-plugins

This makes Claude recognize the new skill.

7. Model per Skill¶

Each skill can specify its own model.

Example:

• Deploy → Sonnet
• Code Review → Haiku
• Complex Analysis → Opus

You don't need to switch models manually.

8. Skill Visibility¶

User Only¶

disable_model_invocation: true

• Only you can run it as a slash command.
• Claude won't invoke it automatically.

Model Only¶

user_invocable: false

• Claude can invoke it automatically.
• You can't call it manually.

9. Skill Arguments¶

Skills can accept parameters.

Example:

/deploy staging

or

/deploy production

The argument is passed into the skill workflow.

10. Dynamic Context¶

Skills can run shell commands before sending the prompt to Claude.

Example:

• Get Git status
• Fetch GitHub PR info
• Read environment details

This injects live project information into the skill.

Useful for team workflows and automation.

11. Security¶

Since skills can execute shell commands:

• Organisations can disable dynamic command execution.
• Prevents untrusted skills from running code on developers' machines.

Quick Revision¶

• Skills = Reusable Markdown workflows.
• Store in skills/<skill-name>/skill.md.
• Description determines when Claude may use the skill.
• Only Name + Description are always in context.
• Full instructions load only when the skill runs.
• Run /reload-plugins after adding or modifying skills.
• Skills can use different models (Haiku, Sonnet, Opus).
• disable_model_invocation: true → User only.
• user_invocable: false → Model only.
• Skills can accept arguments (e.g., /deploy staging).
• Skills can inject dynamic context by running shell commands before execution.

/////////////////////////////////////////////////////////////////////////////////////////

Claude Code Skills (Advanced) – Quick Revision¶

1. Use Skill Creator¶

Instead of manually writing skills, use Skill Creator.

Benefits:

• Creates the skill structure.
• Writes good descriptions.
• Can run evaluations (evals) to verify the skill actually improves your workflow.

Don't add a skill unless it provides measurable value.

2. Skill Evaluation¶

Skill Creator can compare your workflow:

• With the skill
• Without the skill

It generates a report showing whether the skill improves performance or just wastes tokens.

3. Insights¶

Run:

/insights

Shows:

• Claude Code usage report
• Strengths
• Areas to improve
• Workflow insights

4. Power Up¶

Run:

/power-up

Helps onboard you to Claude Code by teaching useful features and workflows.

5. Reference Files Directly¶

Instead of saying:

Read utils.ts

Use:

@utils.ts

Benefit: The file is attached immediately, avoiding an extra Read tool call.

6. Skill Permissions¶

Skills can have their own permissions.

Example:

allowed_tools:
  - bash npm run

The skill can only use those tools.

7. Skill Hooks¶

A skill can define hooks.

Example:

hooks:

Used to run actions before/after tool execution (advanced feature).

8. Context Fork (Sub-agent)¶

Normally:

Skill
   ↓
Uses main conversation

With Context Fork:

Main Chat
      │
      ├── Sub-agent (Skill)
      │
      └── Returns only final result

Benefits:

• Keeps main context clean.
• Reduces token usage.
• Improves response quality.

9. Skill vs Tool Call¶

Skill¶

• Reusable Markdown prompt/workflow.
• Saves repeated typing.
• User productivity feature.

Tool Call¶

• Read file
• Edit file
• Run command

Without tool calls, Claude would only be a chatbot.

10. Automatic Skill Invocation¶

Claude may automatically choose a skill based on:

• Description
• When to Use field

Better descriptions improve automatic invocation.

11. when_to_use¶

Example:

when_to_use:

Provides extra guidance to Claude about when the skill should be selected.

12. Argument Hints¶

Skills can guide users with argument hints.

Example:

/deploy staging
/deploy production

The CLI can suggest valid arguments.

13. Effort per Skill¶

A skill can define its own reasoning effort.

Example:

• Deploy → Medium
• Code Review → High
• Analysis → Max

No need to change global effort settings.

14. Reusable Skills¶

Skills can:

• Be shared with teammates.
• Be packaged as plugins.
• Be reused across multiple projects.

Quick Revision¶

• Skill Creator → Creates and evaluates skills.
• /insights → Shows your Claude Code usage report.
• /power-up → Learn Claude Code features.
• Use @filename to attach files directly.
• Skills can define allowed tools and hooks.
• Context Fork runs a skill in a separate sub-agent.
• Skill ≠ Tool Call (Skill = reusable workflow; Tool Call = file/command operation).
• Improve automatic invocation with description and when_to_use.
• Skills can define arguments, argument hints, and effort levels.
• Well-designed skills become reusable workflows you can share across projects.

/////////////////////////////////////////////////////////////////////////////////

Claude Code Sub-Agents – Quick Revision¶

1. What are Sub-Agents?¶

A Sub-Agent is a separate AI agent that runs in its own context.

It has its own:

• Context
• System prompt
• Tool calls
• Conversation

It returns only the final result to the main agent.

2. Why Use Sub-Agents?¶

Without Sub-Agents:

Main Chat
   ↓
All tool calls + messages + file reads
   ↓
Large, cluttered context

With Sub-Agents:

Main Chat
      │
      ├── Sub-Agent
      │      ↓
      │   Does the work
      │      ↓
      └── Returns only the result

Benefit: Keeps the main conversation clean and improves response quality.

3. Built-in Sub-Agents¶

View available agents:

/agents

Examples:

• Explore → Search codebase (uses Haiku)
• Claude Code Guide → Claude Code documentation
• Setup
• Status

4. Creating a Sub-Agent¶

Claude can generate an agent for tasks like:

• Code Review
• Bug Analysis
• Tech Lead
• Refactoring

Each agent has:

• Description
• Model
• Tools
• System prompt
• Color (UI)

5. When to Use¶

Good for:

• Code reviews
• Long-running analysis
• Searching large codebases
• Background tasks
• Repeatable workflows

6. Parallel Execution¶

Multiple sub-agents can run at the same time.

Example:

Main Agent
   ├── Code Review
   ├── Search Project
   └── Bug Analysis

They work independently and return results when finished.

7. Background Execution¶

Sub-agents continue running while you keep working in the main chat.

You don't have to wait for them to finish.

8. Context Isolation¶

By default:

• Sub-agent does not share the main conversation history.
• It receives only the information needed for its task.

This prevents context pollution.

9. Branch/Fork¶

A Branch (Fork) creates a sub-agent that inherits the current conversation before continuing independently.

Useful when you want to explore an alternative solution without affecting the main thread.

10. Token Usage¶

Sub-agents use additional tokens because each starts with its own context.

More sub-agents = More cost.

Use lightweight models when possible:

• Haiku → Search/exploration
• Sonnet → Code review
• Opus → Complex reasoning only

11. Monitor Usage¶

Use:

/usage

Shows:

• Token consumption
• Number of sub-agents
• Where usage is coming from

Helpful for spotting expensive background agents.

12. Automatic Invocation¶

Claude can automatically launch a sub-agent if its description matches the task.

Example:

Use this agent when code has been modified and needs review.

Good descriptions improve automatic selection.

13. Sub-Agent vs Skill vs Session¶

14. Best Practices¶

• Use sub-agents for long-running or side tasks.
• Keep descriptions specific to avoid unnecessary automatic execution.
• Prefer Haiku or Sonnet unless deep reasoning is needed.
• Monitor token usage with /usage.
• Start a new session if the task is completely unrelated.

Quick Revision¶

• Sub-Agent = Separate AI with its own context.
• Keeps the main conversation clean.
• Can run in parallel and in the background.
• Returns only the final result.
• View agents with /agents.
• Monitor token usage with /usage.
• Branch/Fork = Sub-agent that starts from the current conversation.
• Skill = Reusable workflow.
• Sub-Agent = Isolated execution.
• Session = Completely separate conversation.

///////////////////////////////////////////////////////////////////////////////////////////////////

Claude Code Agent Teams – Quick Revision¶

1. What are Agent Teams?¶

Agent Teams are multiple AI agents that collaborate on the same task.

Unlike Sub-Agents, teammates communicate with each other while working.

2. Sub-Agent vs Agent Team¶

3. How Agent Teams Work¶

              Main Agent (Team Lead)
                     │
        Shared Task List (Created by Lead)
                     │
     ┌─────────┬──────────┬──────────┐
     │         │          │
 UI Agent ↔ Backend ↔ Code Reviewer
     │         │          │
     └─────────┴──────────┘
          Communicate Together
                     │
              Final Result

The Main Agent acts like a Project Manager (PM):

• Creates the task list.
• Assigns work.
• Collects the final result.

4. Creating an Agent Team¶

Simply prompt Claude:

Use a team of 5 agents to implement this feature.

Claude automatically creates specialised teammates (e.g., UI, Backend, Reviewer, QA).

5. Why Agent Teams?¶

Because agents can:

• Coordinate work.
• Wait for each other.
• Reduce conflicts (e.g., editing the same file).
• Specialise in different roles.

6. Verification¶

Agent Teams do not automatically guarantee correctness.

Before starting:

• Review the implementation Plan.
• Verify the Shared Task List.
• Provide tests, screenshots, or requirements.

Human verification is still important.

7. QA Use Case¶

A QA Skill is usually sufficient for:

• Running tests
• Checking regressions
• Verifying changes

For many projects, a QA Skill is cheaper and simpler than a full Agent Team.

8. Token Cost¶

Agent Teams consume more tokens because:

• Multiple agents run simultaneously.
• Agents exchange messages.
• Each agent maintains its own reasoning.

Use them only for complex tasks.

9. Best Practices¶

• Use Sub-Agents for independent background work.
• Use Agent Teams when collaboration is beneficial.
• Keep humans in the loop by reviewing the plan and task list.
• Stop teammates if they go off track.
• Use verification (tests, screenshots, requirements) to validate results.

Quick Revision¶

• Agent Team = Multiple collaborating AI agents.
• Main Agent acts as the Team Lead/PM.
• Team members communicate and work from a shared task list.
• Create teams on demand (no predefined markdown file needed).
• Sub-Agent = Independent worker.
• Agent Team = Collaborative workers.
• QA is often better implemented as a Skill.
• Agent Teams are powerful but token-intensive—use them only when needed.