Claude Code Project Template

A template for LLM-based software engineering with Claude Code, built around a context-engineering driven workflow.

Why Context Engineering?

LLMs perform best when given the right context at the right time. This template implements a structured workflow that progressively builds context through documentation:

1. Tickets capture business requirements (the WHAT and WHY)
2. Research documents existing codebase patterns and constraints
3. Plans synthesize requirements + research into actionable implementation steps
4. Implementation executes with full context from all previous phases

Each phase produces artifacts stored in the thoughts/ directory, creating persistent memory that carries across sessions. When Claude starts work on a ticket, it has access to all the context it needs—no repeated explanations or lost knowledge.

What's Included

• CLAUDE.md - Project instructions with development discipline patterns
• .claude/commands/ - Workflow commands for the 4-phase development cycle
• .claude/agents/ - Specialized agents for codebase and documentation research
• scripts/ - Helper scripts for ticket management
• thoughts/ - Directory structure for persistent context storage

This template is derived from a real Laravel/Nuxt monorepo project. Examples use that stack but the patterns apply to any technology.

Quick Start

1. Clone this repository or copy the files to your project
2. Edit CLAUDE.md with your project details
3. Configure your ticket prefix in all scripts/*.sh files (change TICKET_PREFIX="PROJ")
4. Replace [PREFIX]-XXXX placeholders in command files with your actual prefix
5. Replace [project-root]/ paths with your actual paths
6. Customize tech stack examples (currently Laravel/Nuxt)

Files to Customize

Must Edit

File	What to Change
CLAUDE.md	Your project's architecture, directory structure, and conventions
scripts/*.sh	Set TICKET_PREFIX="PROJ" to your project's prefix in ALL scripts
.claude/commands/commit.md	Your test commands (php artisan test, bun run test, etc.)
.claude/commands/discuss.md	Your tech stack list

Optional Customization

File	What to Customize
.claude/agents/web-search-researcher.md	Add your preferred documentation sources
.claude/references/design-system.md	Your design tokens/conventions (used by /design_explore)
.claude/settings.json	Add your own hooks (currently has ticket validation hooks)
.claude/settings.local.json	Your personal permission settings (not committed)

Ticket Format

This workflow stores tickets as markdown files in Git (in a thoughts/ directory). This keeps requirements, plans, and research alongside your code.

The template uses [PREFIX]-XXXX as a placeholder. Choose a short prefix derived from your project name:

• MYAPP-0001 for a project called "MyApp"
• ORD-0001 for an order management system
• DOC-0001 for a documentation platform

The format is [PREFIX]-XXXX where XXXX is a zero-padded number (0001, 0002, etc.).

Note: This is NOT for external ticket systems like Jira or GitHub Issues. Tickets here are markdown documents committed to your repository that capture requirements, research, and implementation plans.

Development Workflow

This template supports a 4-step development workflow:

Step	Command	Purpose
1	/create_ticket	Capture business requirements (WHAT & WHY)
2	/research_codebase	Research codebase, find patterns & libraries
3	/create_plan	Clarify questions, create detailed implementation plan
4	/implement_plan	Execute implementation using all documents

Additional commands:

• /design_explore - (Optional) Explore and select a visual design for non-trivial UX changes (between steps 3 and 4)
• /commit - Commit changes with pre-commit checks
• /review - Code review (ticket-based or custom scope)
• /discuss - Technical discussion and exploration

Tech Stack Examples

Examples throughout use Laravel/Nuxt patterns. Adapt to your stack:

Example	Alternatives
Laravel	Django, Rails, Express, FastAPI
Nuxt/Vue	Next/React, SvelteKit, Astro
PHP	Python, Ruby, Node.js, Go
Pest/PHPUnit	pytest, RSpec, Jest, Vitest

Directory Structure

The workflow expects a thoughts/ directory for documentation:

thoughts/
├── shared/
│   ├── tickets/      # Ticket definitions ([PREFIX]-XXXX-name.md)
│   ├── research/     # Codebase research documents
│   ├── plans/        # Implementation plans (+ .status.md progress files)
│   ├── reviews/      # Code review documents
│   ├── mockups/      # Design exploration mockups & DECISION.md files
│   └── discussions/  # Technical discussion documents
└── [username]/       # Personal notes (optional)

Agents

Specialized agents for different research tasks:

Agent	Purpose
codebase-locator	Find files and directories by topic
codebase-analyzer	Understand implementation details
codebase-pattern-finder	Find similar implementations to model after
thoughts-locator	Find documents in thoughts/ directory
thoughts-analyzer	Extract insights from thought documents
web-search-researcher	Research external documentation

Key Patterns from This Template

Git Commit Discipline

• Commits after every verified logical step
• Never amend existing commits
• Never auto-push (human decides when to push)

Implementation Phase Discipline

• Tests are part of every phase, not a separate phase
• A phase is complete when all tests pass
• Commit after each phase passes verification

Working Directory Discipline

• Always use absolute paths when switching directories
• Never run frontend commands from backend directory (or vice versa)

Impact Analysis

• Before extending existing code, search for all usages
• Document current contracts and adaptation requirements
• Consider backward compatibility

Scripts

The scripts/ directory contains helper scripts for the ticket workflow:

Script	Purpose
ticket.sh	Find all documents related to a ticket
next-ticket.sh	Generate the next available ticket number
open_tickets.sh	List all open/in-progress tickets
check-ticket-status.sh	Hook: remind to update ticket status on git add
validate-ticket-status.sh	Hook: validate ticket status values

Configuration: Each script has a TICKET_PREFIX variable at the top. Set this to your project's prefix (e.g., MYAPP, ORD).

# Example usage
./scripts/next-ticket.sh          # Returns: PROJ-0001
./scripts/ticket.sh PROJ-0001         # Lists all related docs
./scripts/open_tickets.sh         # Shows open tickets

Hooks

The template includes notification hooks for macOS:

• Notification when Claude needs input
• Notification when a task completes

Ticket validation hooks:

• ./scripts/check-ticket-status.sh - Runs after Bash commands (reminds to update ticket status)
• ./scripts/validate-ticket-status.sh - Runs after Edit/Write (validates status values)

License

This template is provided as-is for use in your own projects. Adapt freely to your needs.