From d2c43f3eb578697bec3f5479da005500df501ce2 Mon Sep 17 00:00:00 2001 From: Shayan Rais Date: Thu, 16 Apr 2026 11:47:52 +0500 Subject: [PATCH] add vibe-coding-to-agentic-engineering presentation Co-Authored-By: Claude --- .../index.html | 1780 +++++++++++++++++ 1 file changed, 1780 insertions(+) create mode 100644 presentation/vibe-coding-to-agentic-engineering/index.html diff --git a/presentation/vibe-coding-to-agentic-engineering/index.html b/presentation/vibe-coding-to-agentic-engineering/index.html new file mode 100644 index 0000000..ac20bac --- /dev/null +++ b/presentation/vibe-coding-to-agentic-engineering/index.html @@ -0,0 +1,1780 @@ + + + + + + + Claude Code — From Vibe Coding to Agentic Engineering + + + +
+ + + + + + + +
+ +

Claude Code

+

From Vibe Coding to Agentic Engineering

+

A journey through every best practice — with a real project.

+
+ + +
+

The Example Project: TodoApp

+
+

Running Example

+

Every technique in this presentation is demonstrated on a TodoApp monorepo — showing the transformation from a plain project to one with full Claude Code configuration.

+
+
+
+

Before (Vibe Coding)

+
# Plain TodoApp +todoapp/ + backend/ + main.py + routes/ + todos.py + users.py + models/ + todo.py + user.py + tests/ + test_todos.py + frontend/ + components/ + TodoList.tsx + Sidebar.tsx + pages/ + index.tsx + todos.tsx + lib/ + api.ts
+
+
+

After (Agentic Engineering)

+
# With Claude Code Best Practices +todoapp/ + .claude/ # Claude Code config + agents/ # Custom subagents + skills/ # Domain knowledge + commands/ # Slash commands + hooks/ # Lifecycle scripts + rules/ # Modular instructions + settings.json # Team settings + settings.local.json # Personal settings + backend/ + main.py + routes/ + todos.py + users.py + models/ + todo.py + user.py + tests/ + test_todos.py + CLAUDE.md # Backend instructions + frontend/ + components/ + TodoList.tsx + Sidebar.tsx + pages/ + index.tsx + todos.tsx + lib/ + api.ts + CLAUDE.md # Frontend instructions + .mcp.json # Managed MCP servers + CLAUDE.md # Project instructions
+
+
+
+ + +
+

What is Vibe Coding?

+

This is where everyone starts. The question is: how fast can you move beyond it?

+
+
+

What Happens (Low Level)

+

> add a notes feature

+

Claude creates /api/notes with a random schema

+

Frontend gets a standalone page with no sidebar nav

+

Tests? None. Patterns? Ignored.

+

Every new feature is a coin flip. Code entropy increases with every prompt.

+
+
+

What We Want (High Level)

+

Claude knows the TodoApp architecture

+

New routes follow existing patterns in routes/todos.py

+

Frontend uses Sidebar.tsx nav and Tailwind tokens

+

Tests written automatically matching test_todos.py style

+

Consistent, tested, production-quality code — every time.

+
+
+
+ + +
+

The Journey

+
+

From Low to High

+

Each section adds techniques that move you from vibe coding toward fully agentic engineering.

+
+
+
1Prerequisites
+
2Better Prompting — Low
+
3Project Memory — Medium
+
4Structured Workflows — Medium
+
5Domain Knowledge — High
+
6Agentic Engineering — High
+
+
+ + + + + + +
+

Installing Claude Code

+
+

Prerequisite

+

Homebrew must be installed on your Mac.

+
+
+

Install via Homebrew

+

Run this in your terminal:

+
brew install claude-code
+
+

Verify Installation

+
claude --version
+

Update Later

+
brew upgrade claude-code
+

Run /doctor anytime to check your installation health.

+
+ + +
+

Login Option A: Subscription

+

Use your Claude Pro or Max subscription via OAuth login:

+
claude +# Select "Claude.ai" at the login prompt +# Opens browser for OAuth
+

Subscription Tiers

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PlanPriceWeekly LimitSonnet 4.5Opus 4.6
Pro$20/moBase limit✓✗
Max 5x$100/mo5× Pro limit✓✓
Max 20x$200/mo20× Pro limit✓✓
+

Weekly limits reset every 7 days. Usage is shared across Claude web, desktop, and Claude Code. Opus 4.6 requires a Max plan.

+
+ + +
+

Login Option B: API Key

+

Pay per token with an Anthropic API key — no weekly caps:

+

Token Pricing (per million tokens)

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ModelInputOutputContext Window
Opus 4.6$5 / MTok$25 / MTok200K (1M beta)
Sonnet 4.5$3 / MTok$15 / MTok200K (1M beta)
Haiku 4.5$0.80 / MTok$4 / MTok200K (1M beta)
+
+

Setup

+
export ANTHROPIC_API_KEY=sk-ant-... +claude
+
+

Best for: Heavy usage, CI/CD pipelines, teams needing predictable billing

+
+ + +
+

Your First Session

+
+

Start Claude Code

+

Navigate to your project and run:

+
cd ~/todoapp +claude
+
+
+

What Happens

+

Claude Code scans your project structure, reads CLAUDE.md (if it exists), and opens an interactive REPL where you can type prompts.

+
+

This IS Vibe Coding

+

Right now, with no CLAUDE.md, no skills, no agents — you're at the Low level. Claude will guess at everything. That's okay. We'll fix it step by step.

+
+ + +
+

The Interface

+
+-----------------------------------------+ +| Claude Code v2.1.33 +| Model: claude-opus-4-6 +| Project: ~/todoapp ++-----------------------------------------+ + +> Type your prompt here...
+

Quick Reference

+
+
⌨
EnterSubmit your prompt
+
↵
Shift+Enter or \New line (multiline input)
+
■
Ctrl+CCancel current generation
+
▶
Ctrl+D or /exitExit Claude Code
+
+
+ + + + + + +
+

Part 2

+

Better Prompting

+

Level: Low — effective prompting that produces real, production-quality results.

+
+ + +
+

Your First Prompt

+
+

Try This

+

Start simple — ask Claude to understand your project:

+
> Read the README.md and give me a summary of this project
+
+

Claude will use the Read tool to open the file, then summarize it. You'll see the tool call in the output.

+

What Just Happened?

+
+
1️⃣
Claude read your promptUnderstood you want a summary
+
2️⃣
Used the Read toolOpened README.md from your project
+
3️⃣
Responded with a summaryBased on actual file contents, not guessing
+
+
+ + +
+

Good vs Bad Prompts

+

The difference between vibe coding and professional usage — shown on our TodoApp:

+
+
+

Vibe Coding

+
> add a notes feature
+

Claude creates a random /api/notes endpoint with a new schema that doesn't match models/todo.py. Frontend page has no sidebar nav.

+

Vague, no context, no constraints.

+
+
+

Professional

+
> In backend/routes/todos.py, add a + PUT /api/todos/{id}/complete endpoint. + Follow the existing route pattern and + update the Todo model's is_completed field. + Add a test in tests/test_todos.py.
+

Specific file, specific endpoint, specific pattern.

+
+
+
+ + +
+

Providing Context

+
+

Key Rule

+

The more context you give, the better Claude performs. Use @ to reference files directly in your prompt.

+
+
+

TodoApp Example

+
> Look at @backend/routes/todos.py and @backend/models/todo.py + Add a priority field to the Todo model and update + the create endpoint to accept it.
+
+

Context Tips

+
+
📄
@file/pathReference specific files for Claude to read
+
📸
Paste screenshotsCtrl+V to paste images of errors or UI
+
📋
Paste error logsCopy the full error message into your prompt
+
+
+ + +
+

Context Window & /compact

+
+

Key Concept

+

Claude has a context window — a limit on how much conversation it can remember. Every prompt, file read, and response fills it up.

+
+ Context window diagram showing how the 1M token limit is divided +
+
+

What Fills Context

+

Your prompts and messages

+

Every file Claude reads

+

Bash command output

+

Claude's own responses

+
+
+

/compact — The Fix

+
> /compact
+

Compresses conversation history into a summary. Claude continues from that summary.

+
+
+
+

Best Practice

+

Run /compact manually at ~50% context usage. Don't wait until it auto-compacts — you lose control over what gets preserved.

+
+
+ + +
+

/plan — Plan Before Code

+
+

Try This

+
> /plan +> Add user authentication to the TodoApp backend
+
+
+
+

Without /plan

+

Claude writes code immediately

+

Wrong approach — redo everything

+

50% of context gone before real work starts

+
+
+

With /plan

+

Claude explores codebase read-only

+

Proposes approach for your approval

+

Right approach from the start

+
+
+
+

Rule of Thumb

+

Always start with plan mode for any task that touches more than 2-3 files or involves architectural decisions.

+
+
+ + +
+

Plan Mode in Practice

+
+

Step by Step

+
# Step 1: Enter plan mode +> /plan + +# Step 2: Describe what you want +> Add pagination to the /api/todos endpoint + +# Step 3: Claude explores and writes a plan +# (reads routes/todos.py, checks models, proposes approach) + +# Step 4: Review the plan and approve it +# Claude then executes the approved plan
+
+
+

TodoApp Benefit

+

In plan mode, Claude discovers your existing SQLAlchemy pagination pattern before writing a single line — no reinventing the wheel.

+
+
+ + +
+

Prompting Best Practices

+
+
🎯
Be specific about files"In backend/routes/todos.py" not "in the backend code"
+
🔎
Describe the problem, not just the fix"The API returns 500 when..." not "make it work"
+
📐
Reference existing patterns"Follow the pattern in routes/todos.py" gives Claude a template
+
🧩
One task at a timeSmall, focused requests get better results than mega-prompts
+
✅
Ask Claude to verify"Run pytest after making changes" catches errors early
+
📸
Provide screenshots for UI issuesA picture is worth a thousand words of description
+
+
+ + + + + + +
+

Part 3

+

Project Memory

+

Level: Medium — make Claude remember your project, conventions, and preferences.

+
+ + +
+

CLAUDE.md & /init

+
+

Key Concept

+

CLAUDE.md is a markdown file that Claude reads at the start of every session. It's your project's instruction manual for Claude.

+
+
+

Create It

+
> /init
+
+

TodoApp CLAUDE.md

+
# CLAUDE.md + +## Project +TodoApp monorepo: FastAPI backend + Next.js frontend. + +## Structure +- backend/routes/ — FastAPI route handlers +- backend/models/ — SQLAlchemy models +- frontend/components/ — React components +- frontend/lib/api.ts — API client + +## Commands +- cd backend && uvicorn main:app --reload +- cd frontend && npm run dev +- cd backend && pytest + +## Conventions +- Backend: follow route patterns in routes/todos.py +- Frontend: use Tailwind, add nav to Sidebar.tsx +- Always add tests for new endpoints
+
+ + +
+

What to Include in CLAUDE.md

+
+
+

Include

+

Project architecture overview

+

Build and test commands

+

Key file locations

+

Coding conventions

+

Common patterns to follow

+

Critical do's and don'ts

+
+
+

Avoid

+

Entire API documentation

+

Long code examples

+

Secrets or API keys

+

Information that changes often

+

Anything over 150 lines total

+
+
+
+

Critical Rule

+

Keep CLAUDE.md under 150 lines. Longer files dilute the instructions — Claude may ignore parts of it. Use Rules and Skills for detail.

+
+
+ + +
+

Keep It Under 150 Lines

+

If You Need More Space

+
+
📄
Use RulesPut topic-specific instructions in .claude/rules/*.md files
+
📚
Use SkillsPut domain knowledge in .claude/skills/ — loaded on demand
+
🔗
Reference filesPoint to docs rather than inlining content
+
+
+

The Hierarchy

+

CLAUDE.md (always loaded, <150 lines) → Rules (path-scoped, auto-loaded) → Skills (on-demand, any length).

+
+
+ + +
+

Rules (.claude/rules/)

+
+

What Are Rules?

+

Modular, topic-specific instructions in individual markdown files. Unlike CLAUDE.md, rules can be scoped to specific paths.

+
+

TodoApp Backend Testing Rule

+
# .claude/rules/backend-testing.md +--- +globs: ["backend/tests/**"] +--- +When writing tests for the backend: +- Use pytest with the existing conftest.py fixtures +- Follow the pattern in test_todos.py: + - Use TestClient from FastAPI + - Create test data with factory functions + - Assert status codes AND response body + - Clean up test database after each test +- Name tests: test_{action}_{entity}_{scenario} +- Always test both success and error cases
+

This rule only activates when Claude is working on test files — keeping context clean for other tasks.

+
+ + +
+

/memory & Memory Hierarchy

+
+

Try This

+
> /memory
+
+

Opens your CLAUDE.md memory files in an editor. Changes here persist across all sessions.

+

Three Scopes (loaded in order)

+
# All combined at session start: +~/.claude/CLAUDE.md # Global — all projects +.claude/CLAUDE.md # Project — shared with team via git +.claude/CLAUDE.local.md # Local — personal, git-ignored
+
+

TodoApp Tip

+

Put your TodoApp CLAUDE.md in the repo root so the whole team shares it. Put personal preferences (editor, style) in CLAUDE.local.md.

+
+
+ + +
+

Memory Best Practices

+
+
📏
CLAUDE.md under 150 linesBrief, focused, high-signal instructions
+
📂
Use rules for specificsPath-scoped rules in .claude/rules/ for targeted guidance
+
👥
Commit project CLAUDE.mdTeam shares project conventions via git
+
🔒
Use .local.md for personal prefsGit-ignored, won't affect teammates
+
🔄
Review and trim regularlyOutdated instructions cause confusion
+
+
+ + + + + + +
+

Part 4

+

Structured Workflows

+

Level: Medium — systematic approaches that prevent wasted effort.

+
+ + +
+

Task Lists

+

For complex tasks, Claude creates a task list to track progress:

+
> Add user authentication to the TodoApp: + - POST /api/register endpoint + - POST /api/login endpoint + - JWT auth middleware + - Protect /api/todos endpoints + - Tests for all auth endpoints
+

Claude breaks this into individual tasks and shows progress as it works through each one.

+
+

Best Practice

+

Break subtasks small enough that each can be completed in under 50% context. Commit after each subtask.

+
+
+ + +
+

/model — Model Selection

+
+

Try This

+
> /model
+
+

Opens the model picker. Match the model to the task:

+
+
🧠
Opus 4.6 (Default)Complex tasks — "Add auth to the TodoApp backend with JWT"
+
⚡
Sonnet 4.5Everyday coding — "Add a completed_at field to the Todo model"
+
🏎
Haiku 4.5Simple tasks — "Read backend/routes/todos.py and summarize the endpoints"
+
+
+

Pro Tip

+

Use Option+P (Mac) or Alt+P to quickly switch models. Use /fast for faster Opus output on non-complex tasks.

+
+
+ + +
+

Workflow Best Practices

+
+
🗺
Always start with plan modeFor any non-trivial task
+
🧩
Break tasks into small piecesEach subtask should complete in under 50% context
+
💾
Commit after each subtaskClean rollback points, not one mega-commit
+
📦
Manual /compact at ~50%Don't wait for auto-compact
+
🤖
Vanilla Claude Code for small tasksSimple tasks don't need elaborate workflows
+
+
+ + + + + + +
+

Part 5

+

Domain Knowledge

+

Level: High — reusable knowledge that Claude loads on-demand.

+
+ + +
+

What Are Skills?

+
+

Key Concept

+

Skills are markdown files that contain domain knowledge — instructions, patterns, or workflows that Claude can load when needed. Think of them as micro-manuals.

+
+

Why Skills?

+
+
📚
Progressive DisclosureKnowledge loaded only when relevant — doesn't bloat every session
+
♻
ReusableSame skill works across agents and workflows
+
👥
ShareableCommit to git — your whole team benefits
+
+
+

Skills vs CLAUDE.md

+

CLAUDE.md = always loaded, every session. Skills = loaded on-demand, when relevant. Use skills for knowledge that's only needed sometimes.

+
+
+ + +
+

Creating Skills: TodoApp Frontend

+

Frontend Conventions Skill

+
# .claude/skills/frontend-conventions/SKILL.md +--- +name: frontend-conventions +description: TodoApp frontend patterns and conventions +--- + +# Frontend Conventions + +When creating or modifying frontend components: + +## Sidebar Navigation +- Add new page routes to frontend/components/Sidebar.tsx +- Use the existing NavLink pattern with icon + label +- Keep alphabetical order in the nav list + +## Component Patterns +- Use functional components with TypeScript +- Import API functions from lib/api.ts +- Follow TodoList.tsx as the reference component +- Use Tailwind classes: bg-white, rounded-lg, shadow-sm + +## API Integration +- All API calls go through lib/api.ts +- Use the existing fetch wrapper with error handling +- Base URL: process.env.NEXT_PUBLIC_API_URL
+
+ + +
+

Skill Frontmatter & Invocation

+

Frontmatter Options

+
+
📜
nameSkill identifier (uses directory name if omitted)
+
📝
descriptionWhen to invoke — helps Claude auto-discover the skill
+
🤖
modelOverride which model runs the skill
+
🔧
allowed-toolsRestrict which tools the skill can use
+
🔁
context: forkRun the skill in an isolated subagent context for complex workflows
+
+

Invocation & Execution Modes

+
# 1. Manual: slash command +> /frontend-conventions + +# 2. Auto: Claude discovers via description field +# (happens when task matches description) + +# 3. Preloaded: in an agent's frontmatter +skills: + - frontend-conventions + +# 4. Optional isolation for heavy workflows +context: fork
+
+ + +
+

Skills Summary

+
+
+

What They Are

+

Markdown files with domain knowledge

+

Live in .claude/skills/

+

Have SKILL.md + optional supporting files

+
+
+

How to Use

+

/skill-name — manual invoke

+

Auto-discovered by description

+

Preloaded into agents via skills:

+
+
+
# Skill directory structure +.claude/ + skills/ + frontend-conventions/ + SKILL.md # Main skill file (required) + backend-patterns/ + SKILL.md + error-handling.md # Supporting file (optional)
+
+ + + + + + +
+

Part 6

+

Agentic Engineering

+

Level: High — custom agents that know your codebase and follow your patterns.

+
+ + +
+

What Are Agents?

+
+

Key Concept

+

Agents are markdown files in .claude/agents/ that define a custom Claude persona with its own tools, model, skills, and behavior.

+
+

Two Ways to Use Agents

+
+
+

As Main Agent

+

Replaces default Claude for your conversation.

+
$ claude --agent frontend-engineer
+
+
+

As Subagent

+

Spawned in an isolated context via Agent tool.

+
Task( + subagent_type="frontend-engineer" + prompt="Add a settings page" +)
+
+
+
+ + +
+

Frontend Engineer Agent

+
+
+

Without Agent

+

> add a settings page

+

Claude creates pages/settings.tsx with:

+

• Inline CSS (no Tailwind)

+

• Direct fetch calls (ignores api.ts)

+

• No sidebar nav entry

+

Standalone page that doesn't fit the app.

+
+
+

With Agent

+

Frontend agent already knows:

+

• Use Tailwind tokens from the design system

+

• Import API functions from lib/api.ts

+

• Add route to Sidebar.tsx

+

• Follow TodoList.tsx component pattern

+

Integrated page matching the app perfectly.

+
+
+
# .claude/agents/frontend-engineer.md +--- +name: frontend-engineer +description: Frontend development following TodoApp conventions +tools: Read, Write, Edit, Bash, Glob, Grep +model: sonnet +skills: + - frontend-conventions +--- +You are a frontend engineer for the TodoApp. +Always add new pages to the Sidebar navigation. +Use the existing API client in lib/api.ts. +Follow TodoList.tsx as your reference component.
+
+ + +
+

Backend Engineer Agent

+
+
+

Without Agent

+

> add a tags feature

+

Claude creates random endpoint structure

+

Different error handling than existing routes

+

No tests, no model validation

+
+
+

With Agent

+

Backend agent follows existing patterns:

+

• Route structure from routes/todos.py

+

• SQLAlchemy model like models/todo.py

+

• Tests matching test_todos.py style

+

• Pydantic schemas for validation

+
+
+
# .claude/agents/backend-engineer.md +--- +name: backend-engineer +description: Backend development following TodoApp patterns +tools: Read, Write, Edit, Bash, Glob, Grep +model: sonnet +skills: + - backend-patterns +--- +You are a backend engineer for the TodoApp. +Follow the route patterns in routes/todos.py. +Create SQLAlchemy models matching models/todo.py. +Always add pytest tests for new endpoints. +Use Pydantic schemas for request/response validation.
+
+ + +
+

Agent Frontmatter

+
# .claude/agents/code-reviewer.md +--- +name: code-reviewer +description: Reviews code for quality and best practices +tools: Read, Grep, Glob +model: sonnet +color: green +skills: + - code-review +memory: user +--- + +You are a code reviewer. Check for security issues, +performance problems, and suggest improvements. +Review your memory for patterns you've seen before.
+

Key Fields

+
+
🔧
toolsWhat the agent can do (Read, Write, Edit, Bash, etc.)
+
📚
skillsKnowledge preloaded at startup
+
🧠
memoryPersistent learning across sessions (user/project/local)
+
+
+ + +
+

Agent Tools & Skills

+

Restricting Tools

+
# Read-only agent — can't modify anything +tools: Read, Grep, Glob + +# Full access agent +tools: Read, Write, Edit, Bash, WebFetch + +# Research-only agent +tools: Read, Grep, Glob, WebSearch, WebFetch
+
+

Key Pattern

+

Skills provide static knowledge (what to do). Agents provide execution context (how to do it, with which tools). Together, they're powerful.

+
+

Choosing a Model

+
+
🧠
opusComplex reasoning, architecture decisions
+
⚡
sonnetGood balance of speed and capability
+
🏎
haikuFast, cheap — great for simple, focused tasks
+
+
+ + +
+

Subagents via Task Tool

+
+

Key Concept

+

Subagents run in an isolated context — separate from the main conversation. They do their work, return a summary, and their context is discarded.

+
+
# Claude spawns a subagent automatically or you can ask: +> Use the frontend-engineer agent to add a settings page + +# Claude uses the Agent tool internally: +Task( + subagent_type="frontend-engineer", + prompt="Add a user settings page to the TodoApp" +)
+

Built-in Subagent Types

+

+ Explore + Plan + Bash + Your Custom Agents +

+
+ + +
+

Commands & Orchestration

+

Commands are the entry points for complex workflows — the Command → Agent → Skills pattern:

+
# .claude/commands/add-feature.md +--- +description: Add a new feature to the TodoApp +model: opus +--- + +# Add Feature Command + +1. Ask the user what feature to add (AskUserQuestion) +2. Invoke the backend-engineer agent for API work: + - Task(subagent_type="backend-engineer", ...) +3. Invoke the frontend-engineer agent for UI work: + - Task(subagent_type="frontend-engineer", ...) +4. Run tests to verify: pytest + npm test +5. Summarize what was built
+
+

Invoke It

+

Commands live in .claude/commands/. Users invoke them as slash commands: > /add-feature

+
+
+ + +
+

Hooks & MCP Servers

+
+
+

Hooks

+

Custom scripts at specific moments in Claude's lifecycle:

+

PreToolUse — validate commands

+

PostToolUse — auto-format code

+

Stop — check task completion

+

SessionStart — load context

+

16 hook events, 5 can block execution.

+
+
+

MCP Servers

+

Connect Claude to external tools via Model Context Protocol:

+

Playwright — browser automation

+

Chrome DevTools — console logs

+

Databases — query data directly

+
> /mcp
+
+
+
+ + +
+

Command → Agent → Skills

+

The full architecture pattern for complex workflows:

+
+-----------------------------------------------+ +| /add-feature (Command) | +| Entry point — user invokes this | +| | | +| +----------+----------+ | +| v v | +| backend-engineer frontend-engineer | +| (Agent) (Agent) | +| | | | +| backend-patterns frontend-conventions | +| (Skill) (Skill) | ++-----------------------------------------------+
+
+

Why It Works

+

Commands = entry point. Agents = orchestration. Skills = domain knowledge. Clean separation, maximum reusability.

+
+
+ + +
+

🎉

+

High — Agentic Engineering

+

Your TodoApp now has: CLAUDE.md for project context, Rules for path-scoped conventions, Skills for domain knowledge, Agents for consistent execution, Commands for orchestrated workflows, Hooks for lifecycle automation, and MCP servers for external tools.

+
+ + +
+

Agent Memory

+
+

Key Feature

+

Agents can learn across sessions. Add memory: user to the frontmatter and the agent builds its own persistent knowledge store.

+
+
# Agent remembers patterns it discovers +~/.claude/agent-memory/code-reviewer/ + MEMORY.md # First 200 lines auto-loaded + react-patterns.md # Topic-specific notes + security-checklist.md # Learned over time
+

Memory Scopes

+

+ user — cross-project + project — team-shared + local — personal +

+
+ + +
+

Agents Summary

+
+
+

Creating Agents

+

Drop .md files in .claude/agents/

+

Set name, tools, model, skills, memory

+

Use /agents to manage interactively

+
+
+

Using Agents

+

Main agent: "agent" in settings.json

+

Subagent: Agent tool spawns it

+

CLI: --agent name

+
+
+

Best Practices

+

Feature-specific agents, not generic ones

+

Preload skills for domain knowledge

+

Use haiku model for simple focused tasks

+
+
+

Architecture

+

Command → Agent → Skills

+

Progressive disclosure of knowledge

+

Single execution context per agent

+
+
+
+ + + + + + +
+

Appendix

+

Reference

+

Command references, workflows, settings, and customization options.

+
+ + +
+

How Claude Uses Tools

+

Claude Code doesn't just generate text — it takes actions using tools:

+
+
+

File Tools

+

Read — Read file contents

+

Edit — Modify existing files

+

Write — Create new files

+

Glob — Find files by pattern

+

Grep — Search file contents

+
+
+

Action Tools

+

Bash — Run shell commands

+

Task — Spawn subagents

+

WebFetch — Fetch URLs

+

WebSearch — Search the web

+

Skill — Invoke skills

+
+
+
+

Important

+

Claude asks for permission before running potentially dangerous commands. Always review what it's about to do.

+
+
+ + +
+

File Operations

+

Reading Files

+
> Read the package.json file
+

Editing Files

+
> In src/utils/format.ts, change the date format from MM/DD to DD/MM
+

Creating Files

+
> Create a new test file for the user service at tests/user.test.ts
+
+

Pro Tip

+

Always tell Claude which file to edit. Don't say "fix the bug" — say "fix the null check in src/handlers/auth.ts line 42".

+
+
+ + +
+

Bash Commands & Search

+

Running Commands

+
> Run the test suite: npm test +> Check which port the server is using +> Install express as a dependency
+

Searching the Codebase

+
> Find all files that import the UserService class +> Search for any TODO comments in the src directory +> Find where the API_KEY environment variable is used
+
+

Pro Tip

+

Use ! prefix for quick bash commands: !git status runs the command and shows output without Claude analyzing it.

+
+
+ + +
+

/help

+
+

Try This

+
> /help
+
+

Shows all available slash commands. This is your starting point when you forget a command.

+
+
+

Daily Use

+

/model — Switch models

+

/plan — Plan before coding

+

/compact — Free up context

+

/cost — Check spending

+
+
+

Project Setup

+

/init — Create CLAUDE.md

+

/memory — Edit memory

+

/config — Settings

+

/doctor — Diagnostics

+
+
+
+ + +
+

/model — Effort Level

+

When Opus 4.6 is selected, you can adjust the effort level:

+
+

How to Set

+

Run /model, select Opus, then use ← → arrow keys to change effort.

+
+
+
🔥
High (Default)Full reasoning depth — complex architecture, tricky bugs, large refactors
+
⚖
MediumBalanced — everyday coding tasks
+
💨
LowMinimal reasoning — quick, simple tasks where speed matters
+
+
+ + +
+

/fast — Faster Output

+
+

Try This

+
> /fast
+
+
+

What It Does

+

Toggles fast mode — same Opus 4.6 model with faster token output. It does NOT switch to a different model.

+
+
+ + +
+

/context & /cost

+
+
+

/context — Visualize Usage

+
> /context
+

Shows a colored grid of your context window — how much is used, what's taking space.

+
+
+

/cost — Track Spending

+
> /cost
+

Shows token usage and cost for the current session.

+
+
+
+ + +
+

/clear & /rewind

+
+
+

/clear — Fresh Start

+
> /clear
+

Clears conversation history completely. Use when switching tasks.

+
+
+

/rewind — Go Back

+
> /rewind
+

Rewinds conversation and/or code to an earlier point.

+
+
+
+

When to Use Which

+

/clear = new topic. /rewind = same topic, wrong turn. /compact = same topic, low on context.

+
+
+ + +
+

/resume — Resume Sessions

+
+

Try This

+
# Resume most recent session +$ claude --resume + +# Or from inside Claude Code: +> /resume
+
+

Opens a session picker showing your recent conversations. Select one to continue where you left off.

+
+ + +
+

/doctor — Diagnostics

+
+

Try This

+
> /doctor
+
+

Checks the health of your Claude Code installation:

+
+
✅
AuthenticationVerifies your login is valid
+
✅
ConfigurationChecks settings.json for errors
+
✅
PermissionsDetects unreachable permission rules
+
✅
UpdatesChecks if a newer version is available
+
+
+ + +
+

/config — Configuration

+
+

Try This

+
> /config
+
+

Opens the interactive settings UI. Key things you can configure:

+
+
🎨
ThemeLight or dark mode
+
📝
Output StyleExplanatory, Learning, or Custom
+
🔔
NotificationsEnable desktop notifications
+
🔒
Permission ModeHow Claude asks for approval
+
+
+ + +
+

/permissions — Tool Access Control

+
+

Try This

+
> /permissions
+
+

Manage what Claude can do without asking. Supports wildcard syntax:

+
// Allow patterns +Bash(npm run *) // Any npm script +Bash(git *) // All git commands +Edit(src/**) // Edit any file in src/ + +// Deny patterns +Bash(rm -rf *) // Block destructive commands +Read(.env) // Block reading secrets
+
+ + +
+

/sandbox — Sandboxing

+
+

Try This

+
> /sandbox
+
+
+

What It Does

+

Enables file and network isolation for bash commands. Safer, with fewer permission prompts.

+
+
+ + +
+

Commands Cheat Sheet

+
+
+

Session

+

/clear — Fresh start

+

/compact — Free context

+

/resume — Continue session

+

/rewind — Undo changes

+
+
+

Model & Mode

+

/model — Switch models

+

/fast — Toggle speed

+

/plan — Plan mode

+

/config — Settings

+
+
+

Project

+

/init — Create CLAUDE.md

+

/memory — Edit memory

+

/permissions — Tool access

+

/sandbox — Sandboxing

+
+
+

Info & Debug

+

/context — Context usage

+

/cost — Token spending

+

/doctor — Health check

+

/help — All commands

+
+
+
+ + +
+

The Commit Workflow

+
+

Ask Claude to Commit

+
> Commit these changes with a descriptive message
+
+

Claude will:

+
+
1️⃣
Run git status & diffReviews all staged and unstaged changes
+
2️⃣
Draft a commit messageFocuses on "why" not "what", following your repo's style
+
3️⃣
Stage and commitAdds specific files (not git add -A) and creates the commit
+
+
+ + +
+

The PR Workflow

+
+

Ask Claude to Create a PR

+
> Create a pull request for these changes
+
+

Claude will:

+
+
1️⃣
Review all commits on the branchAnalyzes the full diff from base branch
+
2️⃣
Write PR title & descriptionSummary, test plan, and changes overview
+
3️⃣
Push and create PR via gh CLIUses GitHub CLI to create the pull request
+
+
+ + +
+

Setting a Default Agent

+
+

Via settings.json

+
// .claude/settings.json +{ + "agent": "frontend-engineer" +}
+
+

Now every time you run claude in this project, you'll talk to the frontend-engineer agent instead of default Claude.

+

Per-Session Override

+
$ claude --agent backend-engineer
+
+

Manage Agents

+

Run /agents to view, create, edit, or delete agents interactively.

+
+
+ + +
+

settings.json Overview

+
+

Settings Hierarchy

+

Settings cascade from most specific to least specific. Higher priority wins.

+
+
# User-writable override order (highest to lowest): +1. Command line flags # --model opus +2. .claude/settings.local.json # Personal, git-ignored +3. .claude/settings.json # Team-shared, committed +4. ~/.claude/settings.local.json # Global personal override +5. ~/.claude/settings.json # Global personal default + +# Policy layer: +managed-settings.json # Organization policy (enforced)
+
+ + +
+

Spinner Verbs

+

Customize the loading messages that appear while Claude thinks:

+
// .claude/settings.json +{ + "spinnerVerbs": { + "mode": "replace", + "verbs": [ + "Cooking", + "Brewing", + "Crafting", + "Conjuring", + "Manifesting" + ] + } +}
+
+ + +
+

Status Line

+

A custom info bar below the composer showing model, context, cost, git branch, etc.

+
+

Quick Setup

+
> /statusline
+
+
// .claude/settings.json +{ + "statusLine": { + "type": "command", + "command": "git branch --show-current 2>/dev/null" + } +}
+
+ + +
+

Output Styles

+
+

Set via /config

+
> /config +# Navigate to Output Style
+
+
+
📖
ExplanatoryClaude explains code patterns and frameworks as it works
+
🎓
LearningClaude coaches you through making changes yourself
+
✏
CustomDefine your own output style
+
+
+ + +
+

Keybindings

+
+

Customize Keys

+
> /keybindings
+
+
+
+

Navigation

+

Option+P — Switch model

+

Ctrl+L — Clear screen

+

Esc Esc — Rewind

+
+
+

Editing

+

Ctrl+G — Open in editor

+

Ctrl+V — Paste image

+

Shift+Tab — Toggle permissions

+
+
+
+ + +
+

Terminal Setup & Vim Mode

+
+
+

/terminal-setup

+
> /terminal-setup
+

Enables Shift+Enter for newlines in IDE terminals.

+
+
+

/vim

+
> /vim
+

Enables vim-style editing mode in the Claude Code prompt.

+
+
+
+ + +
+

Customization Summary

+
+
+

Quick Wins

+

spinnerVerbs — Fun loading messages

+

/statusline — Info bar

+

/config → Output Style

+

/keybindings — Custom keys

+
+
+

Power Features

+

Hooks — Custom lifecycle scripts

+

Plugins — Installable packages

+

MCP Servers — External tools

+

Sandbox — Security isolation

+
+
+
+ + +
+

Debugging Tips

+
+
🩺
Run /doctorFirst thing to try when something isn't working
+
🖥
Background tasks for logsAsk Claude to run the server as a background task so you can see logs while working
+
🌐
Browser MCPs for console logsUse Playwright, Chrome DevTools, or Claude in Chrome to let Claude see browser console
+
📸
Screenshots for UI issuesPaste screenshots directly — Ctrl+V. Worth a thousand words.
+
+
+ + +
+

The Golden Rules

+
+
1️⃣
Always start with plan modeFor any non-trivial task. Review the plan before Claude writes code.
+
2️⃣
Keep CLAUDE.md under 150 linesLonger instructions get diluted. Use skills and rules for detail.
+
3️⃣
Manual /compact at ~50%Don't wait for auto-compact. Stay in control of what's preserved.
+
4️⃣
Commit after each subtaskSmall, frequent commits. Clean rollback points.
+
5️⃣
One task at a timeSmall, focused requests get better results than mega-prompts.
+
6️⃣
Be specific about files"Fix the null check in backend/routes/todos.py line 42" not "fix the bug".
+
+
+ + +
+

Resources

+
+
📖
Claude Code Docscode.claude.com/docs/en
+
💡
Boris Cherny's 12 Tipstips/claude-boris-12-tips-12-feb-26.md
+
🏗
This RepositoryWorking examples of skills, agents, hooks, and the Command → Agent → Skills pattern
+
🔧
Claude Code Hooksgithub.com/shanraisshan/claude-code-hooks
+
+
+ + +
+

Your Next Steps

+
+
1️⃣
Install & LoginGet Claude Code running on your machine today
+
2️⃣
Run /init on your projectCreate a CLAUDE.md — give Claude context about your codebase
+
3️⃣
Use plan mode for your first real taskPick a bug or small feature and work through it with planning
+
4️⃣
Create your first skillDocument a workflow your team repeats and make it a skill
+
5️⃣
Build a feature-specific agentGive Claude domain knowledge about your codebase
+
+
+ + +
+ +

Thank You!

+

Questions?

+

github.com/shanraisshan/claude-code-best-practice

+
+ + + + +
+ + +
+
1 / --
+
← → or Space to navigate
+ + + +