Quick Start Guide

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CLAUDE.md
• .claude/settings.json
• .claude/skills/testing-patterns/SKILL.md
• .claude/agents/code-reviewer.md

This guide provides the essential steps to configure Claude Code within your project. The initial setup involves creating a core directory structure and a few key configuration files. This foundation enables Claude to understand your project's context, conventions, and patterns, allowing for powerful automations like matching code to your standards, running quality gates, and providing deep code reviews.

Following this guide will establish the basic framework for leveraging Claude as a highly integrated AI assistant. For more advanced configurations, refer to the sections on Configuration Reference and GitHub Actions Workflows.

Sources: README.md:3-8

1. Create the .claude Directory

The first step is to create the .claude directory at the root of your project. This directory will house all Claude-related configurations, including agents, commands, hooks, and skills.

mkdir -p .claude/{agents,commands,hooks,skills}

Sources: README.md:81-83

The following diagram illustrates the standard directory structure for a project configured with Claude Code.

This diagram shows the primary configuration files and directories for Claude Code.
Sources: README.md:54-78

2. Add a CLAUDE.md File

Create a CLAUDE.md file in your project root. This file serves as Claude's persistent memory for the project, providing a high-level overview of the stack, key commands, and coding conventions. It is loaded automatically at the start of every session.

Sources: README.md:85-86, README.md:147-148

Example CLAUDE.md:

# Project Name

## Quick Facts
- **Stack**: React, TypeScript, Node.js
- **Test Command**: `npm run test`
- **Lint Command**: `npm run lint`

## Key Directories
- `src/components/` - React components
- `src/api/` - API layer
- `tests/` - Test files

## Code Style
- TypeScript strict mode
- Prefer interfaces over types
- No `any` - use `unknown`

Sources: README.md:88-101, CLAUDE.md

Claude Code looks for this file in the following locations, in order of precedence:

1. .claude/CLAUDE.md
2. ./CLAUDE.md (project root)
3. ~/.claude/CLAUDE.md (user-level)

Sources: README.md:150-154

3. Add settings.json with Hooks

Create a .claude/settings.json file to configure hooks, environment variables, and permissions. Hooks are scripts that trigger on specific events, enabling automation like running tests or blocking edits on protected branches.

Sources: README.md:104-105, README.md:164-165

The following example demonstrates a PreToolUse hook that prevents Claude from making edits directly on the main branch.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "[ \"$(git branch --show-current)\" != \"main\" ] || { echo '{\"block\": true, \"message\": \"Cannot edit on main branch\"}' >&2; exit 2; }",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Sources: README.md:107-121

Hook Event	When It Fires	Use Case
PreToolUse	Before tool execution	Block edits on main, validate commands
PostToolUse	After tool completes	Auto-format, run tests, lint
UserPromptSubmit	User submits prompt	Add context, suggest skills
Stop	Agent finishes	Decide if Claude should continue

Sources: README.md:170-177

4. Add Your First Skill

Skills are markdown documents that teach Claude project-specific patterns, conventions, and domain knowledge. They are stored in .claude/skills/.

Sources: README.md:124, README.md:300-301

To create a skill, make a directory under .claude/skills/ and add a SKILL.md file inside it. The frontmatter description is critical, as Claude uses it to determine when the skill should be applied.

Sources: README.md:124-126, README.md:140-141

Example .claude/skills/testing-patterns/SKILL.md:

---
name: testing-patterns
description: Jest testing patterns for this project. Use when writing tests, creating mocks, or following TDD workflow.
---

# Testing Patterns

## Test Structure
- Use `describe` blocks for grouping
- Use `it` for individual tests
- Follow AAA pattern: Arrange, Act, Assert

## Mocking
- Use factory functions: `getMockUser(overrides)`
- Mock external dependencies, not internal modules

Sources: README.md:128-142, .claude/skills/testing-patterns/SKILL.md

Skill Frontmatter

The SKILL.md file must contain a frontmatter block with the following fields:

Field	Required	Description
name	Yes	Lowercase identifier, should match the directory name.
description	Yes	A detailed explanation of what the skill does and when to use it. Used by Claude for activation.
allowed-tools	No	Comma-separated list of tools Claude can use with this skill (e.g., Read, Grep).
model	No	A specific model to use for this skill (e.g., claude-sonnet-4-20250514).

Sources: README.md:313-320

Summary of Initial Setup

After completing these steps, your project will have the foundational files for Claude Code integration.

File	Purpose	Location
CLAUDE.md	Project memory and high-level context.	./
settings.json	Hooks, environment, and permissions.	.claude/
SKILL.md	A specific piece of domain knowledge.	.claude/skills/{skill-name}/

This setup enables immediate benefits by providing Claude with project context and establishing a framework for automation. From here, you can incrementally add more Skills, define complex workflows with Agents, and integrate with external tools via MCP Servers.

Sources: README.md:424-439