Getting started with Claude Code and ClaudeKit

*ClaudeKit Engineer*

From AI assistant to development partner. Explains how Claude works and guides you through the Engineer Kit with real-world use cases and best/bad practices.

Beginner Friendly · Engineer Kit

What is Claude Code?

Claude Code is an agentic coding environment from Anthropic — not just a chatbot that answers questions, but an AI that can read files, run commands, edit code, and autonomously solve problems while you watch or work on something else.

How it differs from other tools

Context Window — The Most Critical Resource

Claude Code has a context window that holds the entire conversation: messages, files read, command outputs. Performance degrades when the context is full — this is the most important constraint to manage.

Claude "forgets" instructions · Doesn't follow what you said earlier · Repeats completed work · Redoes things that are already done · Ignores CLAUDE.md · Doesn't follow the defined rules

Solution: Use /clear frequently between unrelated tasks.

What is ClaudeKit?

ClaudeKit is a set of workflow templates for Claude Code, consisting of 2 kits:

Engineer Kit · Development workflows (focus of this guide) · Marketing Kit · Content & marketing workflows (coming soon)

ClaudeKit is a paid product. I highly recommend this kit for its effectiveness and the maintainers' active support — it saves a lot of time compared to researching the countless configs and workflows scattered across the internet.

Buy ClaudeKit (30% off)

Engineer Kit (claudekit-engineer) transforms Claude Code from an AI assistant into a development partner. Not a standalone app — it's a .claude/ folder you drop into your project.

Skills · Commands Claude invokes: /ck:cook, /ck:fix, /ck:brainstorm · Hooks · Scripts that run automatically when events occur · Agents · Subagent roles: planner, researcher, tester · Rules · Guidelines that persist across every session

Philosophy: YAGNI + KISS + DRY

YAGNI · You Aren't Gonna Need It — Don't build features you don't need yet · KISS · Keep It Simple — Simplest solution first · DRY · Don't Repeat Yourself — Abstract repeated patterns

Installation & Setup

Step 1: Install ClaudeKit CLI

Install the CLI first (once per machine):

Terminal · npm install -g claudekit-cli

Installer path picker · Select options → get the matching command

1. Project status

2. Config scope

3. Automation level

4. Release channel

5. Existing install advanced

· · · ▸ Your command

If the .claude/.claude\ folder already exists, backup or merge files manually before init.

Project structure after running ck init

project/
├── CLAUDE.md · Template (customize after)
├── AGENTS.md · Agent definitions
├── .gitignore
├── .repomixignore · Repomix ignore patterns
├── release-manifest.json · Kit version manifest
├── plans/ · Plans directory
├── .opencode/ · OpenCode compatibility
└── .claude/ · ClaudeKit config
    ├── .ck.json · Kit metadata
    ├── settings.json · Claude Code settings
    ├── metadata.json · Deletion patterns
    ├── statusline.cjs · Statusline config
    ├── .env.example · Environment template
    ├── .mcp.json.example · MCP config template
    ├── agents/ · 14+ definitions
    ├── hooks/ · 22+ hooks
    ├── rules/ · Workflow rules
    ├── skills/ · 90+ commands
    ├── scripts/ · Utility scripts
    ├── schemas/ · JSON schemas
    ├── output-styles/ · Response formats
    └── session-state/ · Session tracking

Kit installed successfully

Step 2: Customize CLAUDE.md

ck new and ck init (default "Update everything: Yes") automatically create the CLAUDE.md template. Only when you choose "Update everything: No" and untick, CK will skip this file.

After CK creates the template, you can further customize it for your project:

• Edit the generated template file directly — add build commands, code style, and conventions
• Run /init inside Claude Code to regenerate from the codebase (if CLAUDE.md already exists, /init only suggests improvements, won't overwrite)
• Use an LLM to generate it following the 200-line rule

CLAUDE.md (example) · \# Project Name · \## Build Commands - \npm install\ — install dependencies - \npm run dev\ — start dev server - \npm test\ — run tests \## Code Style - Use ES modules (import/export) - Prefer async/await over callbacks - TypeScript strict mode

Keep it under 200 lines. Long files consume context and cause Claude to miss rules (reduced adherence). Only write what's essential: build commands, coding standards, key conventions. If instructions grow, split them into @import or files in .claude/rules/.

Step 3: Set coding level (optional)

Inside a Claude Code session, run the /ck:coding-level command (no arguments) to open an interactive selector to choose 1 of 6 levels. Or set directly: /ck:coding-level 3.

Claude Code · \# Open interactive selector (menu 0-5) · /ck:coding-level · \# Or set level directly · /ck:coding-level · 1 · \# Junior mode

Alternative — Output Styles (native): Claude Code has its own Output styles feature — run /config → select "Output style" → pick from menu. This is an independent Claude Code feature that happens to have some style naming similar to CK coding levels.

Mechanism differences:

• /ck:coding-level writes to .ck.json, guidelines are injected via SessionStart hook each time you open a session.
• Output styles directly change the system prompt (saves outputStyle in .claude/settings.local.json, takes effect from the next session to keep prompt cache stable).

Choose one — use /ck:coding-level or native Output styles, don't enable both at the same time to avoid overlapping guidelines.

· What is God Mode (default)

God Mode assumes you are an expert (15+ years or a domain specialist) — you already know the answer, you just need validation/second opinion/fast typing. Claude acts as force multiplier, not teacher.

Will do · • Default to code, not prose • Production-ready code immediately • Advanced patterns without explanation • Challenge the approach if a serious flaw is found • Flag only critical issues (security, data loss) • Terse — every word must earn its place · Will NOT do · • NO explaining concepts/patterns/syntax • NO "Here's how...", "Let me explain..." • NO adding comments unless requested • NO "Key Takeaways", summaries, next steps • NO clarifying questions for minor ambiguity • NO treating you as if you need hand-holding

If you're new to Claude Code, set level 1 or 2 for explanations. God Mode optimizes velocity but assumes you can debug when Claude is wrong.

Custom Rules — .claude/rules/

For large projects, split instructions into multiple small files inside .claude/rules/ instead of cramming everything into one CLAUDE.md. Rules can scope by file paths via YAML frontmatter — only load into context when Claude touches files matching the pattern, saving context space.

.claude/ directory anatomy

Rules are just one part — .claude/ holds many types of config. Summary of Project scope (shared with team via git) vs Global scope (personal, per-machine):

Project scope · Committed via git · shared with team

./CLAUDE.md              # project instructions (hoặc ./.claude/CLAUDE.md)
./CLAUDE.local.md        # personal — gitignored
./.mcp.json              # MCP servers (team-shared)
./.worktreeinclude       # copy gitignored files vào worktree mới (optional)
./.claude/
├── settings.json        # permissions, hooks, model
├── settings.local.json  # personal — auto-gitignored
├── rules/*.md           # topic rules (path-scopable)
├── skills/<name>/       # /skill-name + bundles
├── commands/*.md        # /command (legacy — prefer skills)
├── agents/*.md          # subagents
├── agent-memory/        # project subagent memory (memory: project)
└── output-styles/*.md   # system-prompt styles

.\CLAUDE.md              # project instructions (hoặc .\.claude\CLAUDE.md)
.\CLAUDE.local.md        # personal — gitignored
.\.mcp.json              # MCP servers (team-shared)
.\.worktreeinclude       # copy gitignored files vào worktree mới (optional)
.\.claude\
├── settings.json        # permissions, hooks, model
├── settings.local.json  # personal — auto-gitignored
├── rules\*.md           # topic rules (path-scopable)
├── skills\<name>\       # /skill-name + bundles
├── commands\*.md        # /command (legacy — prefer skills)
├── agents\*.md          # subagents
├── agent-memory\        # project subagent memory (memory: project)
└── output-styles\*.md   # system-prompt styles

Global scope · Your machine only · never committed

~/.claude.json           # app state, personal MCP, UI prefs
~/.claude/
├── CLAUDE.md            # global instructions
├── settings.json        # default settings
├── keybindings.json     # custom shortcuts
├── rules/*.md           # user-level rules
├── skills/              # personal skills
├── commands/            # personal commands
├── agents/              # personal subagents
├── agent-memory/        # subagent memory (memory: user)
├── output-styles/       # personal styles
├── plugins/             # installed plugins (auto-managed)
└── projects/<project>/memory/   # auto-memory (Claude tự ghi)

%USERPROFILE%\.claude.json  # app state, MCP, UI prefs
%USERPROFILE%\.claude\
├── CLAUDE.md            # global instructions
├── settings.json        # default settings
├── keybindings.json     # custom shortcuts
├── rules\*.md           # user-level rules
├── skills\              # personal skills
├── commands\            # personal commands
├── agents\              # personal subagents
├── agent-memory\        # subagent memory (memory: user)
├── output-styles\       # personal styles
├── plugins\             # installed plugins (auto-managed)
└── projects\<project>\memory\  # auto-memory (Claude tự ghi)

Path-specific rules — scope rules by file pattern

· Only load rules when needed

Add YAML frontmatter to the top of a rule file to limit its scope. Claude only loads the rule into context when working with files that match the glob pattern — reduces context bloat while keeping domain-specific guidance (auth, db, UI, tests…).

.claude/rules/typescript-api.md · --- description: TypeScript API conventions applies_to: - "src/api/\\/\.ts" - "src/services/\\/\.ts" --- · \# TypeScript API Rules - Dùng zod schema cho mọi request/response body. - Trả Result\<T, E\> thay vì throw ở service layer. - Auth middleware phải chạy trước validation middleware.

· Rules are guidance, NOT enforcement

Rules (and CLAUDE.md) are instructions Claude reads, not Claude Code config that enforces. Claude may not follow if instructions conflict or are ambiguous. For guaranteed behavior, use:

• Hooks (settings.json) — scripts that run before/after tool calls
• Permissions — allow/deny specific tools/commands

CLAUDE.md vs Settings: 2 different merge mechanisms

Commands ≈ Skills · Commands and skills now share the same mechanism. New workflows should use skills/<name>/SKILL.md — bundle SKILL.md + supporting files (checklists, scripts, reference docs). If a skill and command share the same name, skill wins. · Auto-memory · Claude automatically writes notes to ~/.claude/projects/<project>/memory/MEMORY.md (first 200 lines / 25KB loaded each session). Topic files lazy-load. Toggle: /memory or autoMemoryEnabled setting.

The difference: CLAUDE.md vs rules/

· Path-specific rules

Use YAML frontmatter with a paths field so the rule is only active when Claude touches matching files:

.claude/rules/api-design.md · --- paths: - "src/api/\\/\.ts" - "src/server/\\/\.ts" --- \# API Development Rules - All endpoints must validate input via Zod - Use standard error response format - Include OpenAPI docs comments

Rules without a paths field load unconditionally. With paths, they trigger when Claude reads files matching the pattern.

Best Practices for writing rules

DO · • Split rules by domain/concern (i18n-rules.md, testing-rules.md...) • Write concisely, use bullets/checklists — Claude parses fast • Kebab-case, descriptive names (api-error-handling.md) • Include examples (good vs bad) • Reference exact paths when applying to a specific folder · DON'T · • Write verbose rules like documentation • Duplicate content between CLAUDE.md and rules/ • Create rules for YAGNI things (1-time use)

Common Use Cases

UC1: Multi-language app (i18n) · Create .claude/rules/i18n-rules.md for a multilingual app. · i18n-rules.md · \# i18n Rules \## Scope Apply to all user-facing text in src/components/ and src/pages/. \## Rules - Mọi user-visible string PHẢI dùng \t('key')\ từ \useTranslation()\ - Translation keys tại \src/i18n/{locale}/{namespace}.json\ - Support locales: vi (default), en, zh, ja - Key naming: \section.component.element\ - KHÔNG i18n: code snippets, entity IDs, technical identifiers \## Khi thêm text mới 1. Thêm key vào \src/i18n/vi/{ns}.json\ trước 2. Copy key sang 3 locales còn lại với placeholder 3. Cập nhật \src/i18n/index.ts\ nếu tạo namespace mới · UC2: API Error Handling · Enforce a discriminated union pattern for API responses. · api-error-handling.md · \# API Error Handling \## Pattern Mọi API call phải wrap trong try/catch, return discriminated union: {ok: true, data} \| {ok: false, error} \## Error Types (src/types/errors.ts) - NetworkError, ValidationError, AuthError, ServerError \## UI Display - Toast cho transient errors (NetworkError) - Inline form errors cho ValidationError - Redirect to /login cho AuthError · UC3: Database Migration Safety · Avoid breaking changes when migrating the DB. · db-migration.md · \# Database Migration Rules - NEVER drop columns trong migration — mark deprecated trước, drop ở release sau - Mọi migration phải có \up()\ VÀ \down()\ — rollback-safe - Index concurrent (Postgres: \CONCURRENTLY\) cho tables \> 10k rows - Test migration trên copy of prod data trước khi merge · UC4: Testing Standards · Coverage targets and conventions for tests. · testing-rules.md · \# Testing Rules \## Coverage - Unit tests cho business logic: \> 80% - Integration tests cho API endpoints - E2E tests cho critical user flows (login, checkout) \## Conventions - Test files: \\*.test.ts\ cạnh source file - Arrange/Act/Assert pattern - Dùng factories thay vì fixtures hardcode - Mock external services, KHÔNG mock internal modules · UC5: Security Baseline · Baseline security rules for every project. · security-rules.md · \# Security Rules - NEVER log secrets, tokens, passwords - Input validation: Zod schema at API boundary - SQL: prepared statements only, no string concat - Auth middleware check trên mọi protected route - CORS whitelist từ env, không wildcard - Dependencies: audit weekly với \npm audit\

Loading Order

When opening a session, Claude reads memory files from top to bottom, then concatenates all of them into context — they don't overwrite each other.

Rules with paths frontmatter only activate when Claude touches a file matching the pattern — they aren't loaded at startup. This lets you write directory-specific rules without bloating CLAUDE.md.

· Recommended size

Anthropic recommends CLAUDE.md should be under 200 lines. Longer files will cause adherence to drop — meaning Claude will miss or ignore more of your rules because it has too much information to process. Rule files should also be kept short. When CLAUDE.md approaches 200 lines, split it into .claude/rules/ by topic (e.g. api-design.md, testing.md, security.md). Name files descriptively so both your team and Claude can quickly find them via Grep.

Advanced file-loading mechanisms

For large projects or when you want to share rules across multiple repos, you have 4 context-expansion mechanisms. The diagram below shows how each mechanism pulls additional files into the base CLAUDE.md.

@import syntax · Embed other files directly into CLAUDE.md ·

In CLAUDE.md, write @docs/coding-standards.md or @~/.claude/my-prefs.md to embed the file's content at that location. Claude supports both relative and absolute paths, with a maximum depth of 5 nested imports (hops). Use this to split long content into separate files while keeping CLAUDE.md concise.

CLAUDE.md · @docs/coding-standards.md @~/.claude/rules/security.md @.claude/rules/testing.md

--add-dir flag · Open additional working directories in the same session ·

By default, Claude Code only reads files in the directory you launched it from (working directory). The --add-dir flag lets you open additional directories in the same session — useful for monorepos or when you need to reference directories like ../shared, ../design-system outside your current project.

All three activation methods are equivalent: the --add-dir flag at launch, the slash command /add-dir during a session, or declaring additionalDirectories in settings.json.

Kích hoạt --add-dir · \# Flag khi launch · claude --add-dir ../shared --add-dir ../design-system \# Hoặc slash command trong session /add-dir ../shared

Important note: by default, Claude does not load CLAUDE.md or CLAUDE.local.md files from directories added via --add-dir — to maintain backward compatibility with older projects. If you want Claude to apply memory from those directories, enable this environment variable before launching:

Bật nạp memory cho --add-dir · export CLAUDECODEADDITIONALDIRECTORIESCLAUDE_MD=1 claude --add-dir ../shared

Once enabled, every CLAUDE.md or CLAUDE.local.md in added directories will be loaded alongside the main project, allowing Claude to understand the conventions of each workspace within the same session. This feature is available from version 2.1.20 and is opt-in for backward compatibility reasons.

CLAUDE.local.md · Personal notes, not committed to git ·

File for your personal preferences within the project (sandbox URLs, test accounts, personal debug commands). Add CLAUDE.local.md to .gitignore to keep it out of commits. Claude loads this file alongside CLAUDE.md but it's only visible on your machine — your team won't see it.

Symlinks share rules · Share one ruleset across multiple projects ·

The .claude/rules/ directory supports symlinks — keep your team's canonical ruleset in one place and link it into each project. When you update a rule, all projects get it simultaneously. Claude detects circular symlinks and skips them automatically.

Share rules qua symlinks · ln -s ~/shared-claude-rules .claude/rules/shared ln -s ~/company-standards/security.md .claude/rules/security.md

7 Core Commands for Beginners

/ck:brainstorm · Explore solutions before committing. Output: Trade-off analysis, pros/cons, recommendation. · /ck:brainstorm How should we implement real-time notifications? WebSockets vs SSE vs polling?

/ck:plan · Detailed planning for complex features. Research → Plan → Files list → Success criteria. · /ck:plan Implement user authentication with OAuth2 (Google, GitHub)

/ck:cook

The main command for implementation. 8-step workflow: Research → Review → Plan → Review → Implement → Review → Test → Finalize.

/ck:cook Add a logout button to the navbar

--fast: Skip research \| --auto: Skip all review gates

/ck:fix · 7-step process (0-6): Mode Selection → Scout → Diagnose → Complexity → Fix → Verify → Finalize. · /ck:fix Users can't login after session timeout - seeing "Invalid token" error

/ck:ask · Ask technical questions. Like having a senior engineer by your side. · /ck:ask How does our authentication middleware handle token refresh?

/ck:test · Run tests. Supports multiple test runners. · /ck:test src/auth/ \# Test specific folder

/ck:watzup · Review session changes. Files modified, git diff analysis, impact assessment. · /ck:watzup

Real-World Use Cases

Build a new feature (Beginner) · Add a user settings page with a dark mode toggle and notification preferences. · Full Workflow · /ck:brainstorm User settings page: dark mode + notifications. Should we store in localStorage or backend? Component structure? \# → Output: plans/reports/brainstorm-260414-user-settings.md · /ck:plan Implement per brainstorm report at plans/reports/brainstorm-260414-user-settings.md \# → Creates implementation plan with phases · /ck:cook plans/260414-xxxx-user-settings/plan.md \# Execute: implement → review → test → done · /ck:git cm \# Commit with message · Feature complete with proper planning. Code reviewed, tested, committed.

Fix a bug quickly (Beginner) · Form validation doesn't show an error message when the email is invalid. · Quick Fix Workflow · /ck:fix Email validation in signup form doesn't show error message. File: src/components/SignupForm.tsx Expected: "Invalid email" appears below input Actual: No message, just red border /ck:test src/components/SignupForm.test.tsx · Bug fixed with regression test. Automated pipeline: scout → diagnose → fix → test → verify.

Onboard a new codebase (Intermediate) · Joining a new team, need to understand the codebase quickly before contributing. · Exploration Workflow · /ck:scout src/ \# Explore structure · /ck:ask How does the authentication flow work? /ck:ask Explain src/services/auth/token-handler.ts /ck:ask What patterns does this codebase follow? · Understand architecture, key flows, and patterns in 30 minutes instead of 2 days of reading docs.

Safe refactoring (Intermediate) · Legacy module of 500 LOC needs cleanup but you're afraid of breaking existing functionality. · Safe Refactor Workflow · /ck:ask Analyze src/legacy/user-manager.js What are the hidden dependencies? Side effects? /ck:plan Refactor user-manager.js into smaller modules. Must maintain all existing behavior. Write tests first. \# → Creates implementation plan with phases · /ck:cook \<plan-path\> \# Execute: implement → review → test → done · /ck:code-review · \# Verify no regressions · Modular code, with tests, zero regression. Confident refactoring.

Build UI from Figma (Intermediate) · PM sends a Figma mockup, need to implement pixel-perfect with animations. · UI Implementation Workflow · /ck:frontend-design \[paste Figma URL hoặc screenshot\] \# Auto-activates /ck:ui-ux-pro-max (design intelligence) · \# Claude generates với đúng spacing, colors, animations · /ck:ui-styling Add dark mode support cho component vừa tạo /ck:test src/components/NewFeature.test.tsx · Pixel-perfect UI, responsive, with dark mode. No designer review needed.

Best Practices

DO: Give Claude a way to verify results

Single highest-leverage tip.

Bad · implement email validation · Good · write validateEmail function. Test cases: user@example.com → true Run tests after implementing.

DO: Brainstorm → Plan → Cook

/ck:brainstorm \[explore options\] · /ck:plan \[detail implementation\] · /ck:cook \[implement + test\] · /ck:git cm \[commit\]

/ck:cook already includes testing. Use /ck:test [path] separately when you need to test a specific folder.

· When to skip /ck:brainstorm?

Use /ck:plan directly when:

• You already know the approach (fixing a specific bug, adding an endpoint per spec)
• Simple task, no need to explore alternatives
• You already have a design/spec from Figma or PRD

Use /ck:brainstorm before: you don't know which approach is best, you need trade-off analysis (WebSockets vs SSE), or a new feature without precedent.

· UI Features: Mockup before implementing

For UI-heavy features, add a mockup step to review first:

/ck:brainstorm → /ck:plan → /ck:frontend-design (mockup) → Review → /ck:cook

HTML mockups with mock data are faster than the real implementation. Catch design issues early, avoid rework.

DO: Provide specific context

Bad · add tests for auth · Good · write tests for src/auth/token-refresh.ts: - successful refresh with valid token - failure when token expired \> 7 days - concurrent refresh requests

DO: Clear context frequently

When to use /clear:

• Switching to a completely different task
• Claude has been wrong more than 2 times on the same issue
• Claude starts "forgetting" instructions

Bad Practices (Avoid!)

Kitchen sink session

Doing many unrelated tasks in one session → context fills with noise, Claude gets confused.

"Fix login" → "Add dark mode" → "Optimize images" → "Back to login"

Fix: /clear between each unrelated task

Correct the same issue repeatedly

Claude is wrong → correct → still wrong → correct again... Context polluted with failed approaches.

Fix: After 2 failed corrections → /clear and write a better prompt

Skip planning for "simple" tasks

"This is simple, no need to plan" → 3 hours later, still debugging edge cases.

Fix: /ck:plan --fast for lightweight planning

Trust without verify

Claude: "Done!" → Ship to production → Everything broken.

Fix: /ck:test + manual testing + code review → then ship

Overly vague prompts

"make it better", "fix the bug", "add auth" — not enough context for Claude to do it right.

Fix: Specific symptom + location + expected behavior

Common Workflow Patterns

Pattern 1: Quick fix (\< 5 min) · /ck:cook --fast Fix typo /ck:git cm "fix: typo" · Pattern 2: Standard feature · /ck:brainstorm /ck:plan → /ck:cook /ck:git cm · Pattern 3: Complex (multi-day) · Day 1: /ck:brainstorm → /ck:plan Day 2+: /ck:cook \[Phase N\] /clear between phases · Pattern 4: Bug investigation · /ck:debug \[symptom + logs\] Phân tích root cause → fix thủ công hoặc /ck:fix

Common Workflow Patterns

Beginner · Week 1 · /ck:brainstorm · /ck:plan · /ck:cook · /ck:fix · /ck:ask · /ck:test · /ck:git · Intermediate · Week 2-4 · /ck:scout · /ck:code-review · /ck:debug · /ck:ship · /ck:watzup · /ck:frontend-design · /ck:ui-styling · Advanced · Month 2+ · /ck:team · /ck:autoresearch · /ck:predict · /ck:security · /ck:loop · /ck:scenario · /ck:xia · /ck:bootstrap 70+ other skills

This cheat sheet lists 14 commonly used commands. See the full reference table, detailed syntax, and real-world examples for all commands at vividkit.dev/guides/commands.

Cheat Sheet

This cheat sheet lists 14 commonly used commands. See the full reference table, detailed syntax, and real-world examples for all commands at vividkit.dev/guides/commands.