Repository Structure

To turn Claude Code from a generic assistant into a specialized member of your team, this repository utilizes a specific configuration hierarchy. All AI-specific logic, domain knowledge, and automation rules reside within the .claude directory.

Directory Overview

The following structure defines how Claude interacts with your codebase, enforces standards, and executes custom workflows.

.
├── .claude/
│   ├── agents/          # Specialized AI personas and checklists
│   ├── commands/        # Custom CLI commands (e.g., /ticket)
│   ├── hooks/           # Automated scripts and evaluation logic
│   ├── skills/          # Domain-specific knowledge and patterns
│   ├── settings.json    # Core configuration and automation triggers
│   └── settings.md      # High-level constraints and project rules
├── .github/
│   └── workflows/       # Scheduled LLM maintenance and PR reviews
└── .mcp.json            # Model Context Protocol integrations (Jira, Linear, etc.)

Where to Place Custom Logic

1. Domain Knowledge (.claude/skills/)

Place "Skills" here when you want Claude to follow specific patterns for UI components, testing, or API design. Each skill is typically a directory containing a SKILL.md file that explains the "how-to" for a specific domain.

• Example: .claude/skills/testing-patterns/SKILL.md ensures Claude writes tests using your preferred library and mocking strategy.

2. Specialized Assistants (.claude/agents/)

Use "Agents" for complex, multi-step roles. Unlike general prompts, agents define a persona with a specific checklist and success criteria.

• Example: .claude/agents/code-reviewer.md defines the strictness levels for PR audits, focusing on TypeScript safety and error handling.

3. Workflow Automation (.claude/hooks/)

Hooks are the "brain" of the integration. They allow you to run scripts before or after Claude performs actions.

• Skill Evaluation: The skill-eval.js hook is a primary component that analyzes your intent and automatically activates the relevant skills from the /skills folder based on the files you are editing or the keywords in your prompt.

4. Custom CLI Commands (.claude/commands/)

You can extend the Claude Code CLI by adding Markdown-based command definitions.

• Example: Placing a ticket.md in this folder enables the /ticket command, allowing Claude to interface with external tools like Jira or Linear to read requirements or update statuses.

5. Global Constraints (.claude/settings.md)

This file acts as the "Constitution" for the project. Use it to define absolute "Do's and Don'ts"—such as "Never edit the main branch directly" or "Always use functional components."

Continuous Maintenance

While the .claude folder handles local interaction, the repository uses .github/workflows to run Claude-powered agents on a schedule:

| Workflow | Purpose | | :--- | :--- | | pr-claude-code-review.yml | Automatically triggers a deep code review on every PR. | | scheduled-claude-code-docs-sync.yml | Synchronizes documentation with recent code changes monthly. | | scheduled-claude-code-quality.yml | Performs weekly "drive-by" refactoring and linting. |

External Integrations

To connect Claude to your external ecosystem, modify the .mcp.json file. This configuration uses the Model Context Protocol to bridge the gap between your code and project management tools, enabling Claude to perform actions like fetching ticket acceptance criteria or posting PR comments.