Core Concepts

Relevant source files

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

• README.md
• CLAUDE.md
• .claude/settings.json
• .mcp.json
• .claude/skills/testing-patterns/SKILL.md

This project demonstrates a structured approach to integrating the Claude Code LLM into a software development workflow. The core concept is to build a set of reusable "skills," specialized "agents," and automated "hooks" to create a "super-powered teammate" that understands project conventions, enforces quality, and automates repetitive tasks. This system enables deep integration with external tools like JIRA and automates processes such as code review, documentation updates, and dependency audits.

The configuration is primarily managed within a .claude directory, which centralizes the project-specific knowledge and automation rules. This allows Claude to generate code that matches established patterns, review changes against a detailed checklist, and execute complex workflows triggered by slash commands or scheduled events.

Sources: README.md:3-8

Directory Structure

The project's configuration for Claude Code is organized within the .claude directory, with additional configuration files in the project root and .github for CI/CD integration.

Sources: README.md:92-127

This diagram illustrates the key directories and files that define Claude's behavior.

Project Memory (CLAUDE.md)

CLAUDE.md serves as Claude's persistent memory for a project. It is loaded automatically at the start of a session and provides essential context about the project's stack, architecture, commands, and coding conventions. This file is the foundation for ensuring Claude's outputs are aligned with the project's standards.

Key Information to Include:

• Project stack (e.g., React, TypeScript, Node.js)
• Key commands (npm test, npm run lint)
• Important directories and their purpose
• Code style guidelines (e.g., TypeScript strict mode, no any)
• Git conventions (branch naming, commit format)
• Critical rules for error handling and UI states

Claude searches for this file in a specific order of precedence: .claude/CLAUDE.md, ./CLAUDE.md (root), and finally ~/.claude/CLAUDE.md (user-level).

Sources: README.md:168-182, CLAUDE.md:1-50

Configuration and Automation (settings.json)

The .claude/settings.json file is the central configuration point for hooks, environment variables, and permissions. Hooks are a key mechanism for automating tasks and enforcing quality gates at different stages of Claude's operation.

Sources: README.md:184-188

Hooks

Hooks are scripts or commands that are triggered by specific events in the Claude Code lifecycle. They can be used to block actions (e.g., preventing edits on the main branch), auto-format code, run tests, or suggest skills.

This diagram shows the lifecycle of a tool execution with pre- and post-hooks.

Hook Events

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 a prompt	Add context, suggest skills
Stop	Agent finishes	Decide if Claude should continue

Sources: README.md:199-206

Example Hook Configuration

This PreToolUse hook prevents Claude from editing files 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:144-158, .claude/settings.json:3-16

Domain Knowledge (Skills)

Skills are markdown documents (SKILL.md) that teach Claude project-specific patterns, conventions, and best practices. They are stored in .claude/skills/ and are a core component for ensuring generated code is idiomatic to the repository. Claude uses the description field in a skill's frontmatter to determine when it should be applied.

Sources: README.md:470-473, README.md:496-501

Skill Structure

Each skill is defined in a SKILL.md file and contains frontmatter for configuration and markdown content for instructions.

---
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:160-166, .claude/skills/testing-patterns/SKILL.md:1-16

SKILL.md Frontmatter

Field	Required	Description
name	Yes	Lowercase identifier, should match the directory name.
description	Yes	Explains what the skill does and when to use it. Critical for automatic activation.
allowed-tools	No	Comma-separated list of tools Claude can use with this skill.
model	No	Specific model to use for this skill (e.g., claude-sonnet-4-20250514).

Sources: README.md:486-494

Specialized Assistants (Agents)

Agents are specialized AI assistants defined in markdown files within .claude/agents/. They are designed for focused tasks and have their own system prompts and instructions. For example, a code-reviewer agent can be instructed to follow a specific checklist when reviewing code.

Agents are defined with frontmatter and a system prompt.

---
name: code-reviewer
description: Reviews code for quality, security, and conventions. Use after writing or modifying code.
model: opus
---

# Agent System Prompt

You are a senior code reviewer...

## Your Process
1. Run `git diff` to see changes
2. Apply review checklist
3. Provide feedback

Sources: README.md:503-527

External Integrations (MCP Servers)

MCP (Model Context Protocol) servers allow Claude Code to connect to external tools like JIRA, GitHub, and Slack. This is configured in the .mcp.json file in the project root. MCP servers act as a local bridge, providing Claude with a set of tools (e.g., jira_get_issue, github_create_pr) to interact with external APIs.

Sources: README.md:218-223

This diagram shows how Claude Code interacts with an external API via an MCP server.

.mcp.json Configuration

The .mcp.json file defines the servers Claude can connect to.

Field	Required	Description
type	Yes	Server type: stdio (local process) or http (remote).
command	For stdio	The executable to run (e.g., npx).
args	No	Command-line arguments for the executable.
env	No	Environment variables, supporting ${VAR} expansion.

Sources: README.md:239-247

An example configuration for JIRA and GitHub integration:

{
  "mcpServers": {
    "jira": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-jira"],
      "env": {
        "JIRA_HOST": "${JIRA_HOST}",
        "JIRA_EMAIL": "${JIRA_EMAIL}",
        "JIRA_API_TOKEN": "${JIRA_API_TOKEN}"
      }
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

Sources: .mcp.json:2-22, README.md:280-293

Advanced Automation

The core concepts are combined to create powerful, automated workflows.

Skill Evaluation Hooks

A UserPromptSubmit hook can trigger a skill evaluation engine. This system analyzes the user's prompt for keywords, file paths, and intent to automatically suggest and activate relevant skills, ensuring project conventions are always applied.

This flowchart outlines the skill evaluation process.

GitHub Actions

The project leverages GitHub Actions to automate tasks on a schedule or in response to events like pull requests. A common use case is an automated PR review that invokes a code-reviewer agent to check for quality and adherence to standards. Other workflows can perform scheduled maintenance like syncing documentation, auditing dependencies, or running quality checks.

Sources: README.md:562-565, README.md:592-596