This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
- Quick Commands
- Project Stack
- Development Approach
- Tools for Review
- MCP Integration
- Shortcuts
- Related Documentation
⚡ Pro Tip: Use shortcuts like
QNEW,QCODE,QGITfor faster workflow. See Shortcuts Reference below.
# Development
composer dev # Start dev environment (server + queue + vite)
npm run build --mode production # Production build
npm run build --mode staging # Staging build
# Laravel
php artisan migrate && php artisan db:seed
php artisan queue:work
php artisan test --filter TestName
# Code Quality
./vendor/bin/pint --dirty # Format PHP code
npm run prettier # Format JS/CSSLaravel 12 (PHP 8.2+) with Livewire 3 + Alpine.js + Tailwind CSS
- Database: MySQL with migrations
- Auth: Laravel Jetstream + Spatie Permission (RBAC)
- Queue: Laravel queues for background processing, AWS SQS (production)
- Storage: AWS S3 (production)
- Logging: Sentry for error tracking, AWS Cloudwatch for logs (production)
- Deployment: Laravel Vapor + AWS Lambda (production)
- Integrations: Google Sheets, OCR, DocuSign, WhatsApp, CTOS (LARACTOS)
-
Core PHP & Laravel Standards: docs/Guidelines/LARAVEL_PHP_GUIDELINES.md
- Fundamental PHP/Laravel coding standards (PSR-12, typing, conventions)
- Base patterns for classes, methods, and file structure
-
Project Development Conventions: docs/Guidelines/LARAVEL_DEVELOPMENT_CONVENTIONS.md
- Project-specific implementation rules (MUST/SHOULD practices)
- TDD approach, testing standards, and code organization
- Architecture patterns and domain-specific conventions
-
Laravel Boost Integration: docs/Guidelines/LARAVEL_BOOST_GUIDELINES.md
- Laravel Boost MCP tools (search-docs, tinker, etc.)
- Laravel Documentation referencing
- MCP server tools and workflow optimization
- Version-specific package guidelines and tooling
- Always start with Laravel Boost MCP tools (search-docs, tinker, etc.)
- Follow existing project structure and conventions
- Prefer Laravel's built-in features over custom solutions
- Reference guidelines in hierarchical order when in doubt
// Example: Always search docs first
laravel-boost:search-docs(['livewire', 'components'])Remember: Guidelines work together - PHP standards provide the foundation, project conventions add specific rules, and Boost integration optimizes your workflow.
# Use during review
search-docs ['validation', 'authorization'] # Check Laravel docs
tinker # Test logic quickly
database-query # Verify database changes
browser-logs # Check frontend errors# Local testing
composer dev # Start development environment
php artisan migrate:fresh --seed # Fresh database
npm run dev # Frontend hot reload- Clear Feedback: Provide specific, actionable comments
- Code Suggestions: Include corrected code examples when possible
- Priority: Mark critical vs. minor issues clearly
- Re-review: Schedule follow-up review after changes
- Final Checks: Ensure CI/CD passes
- Merge Strategy: Use appropriate merge strategy (squash/merge)
- Deployment: Verify staging deployment works
- Documentation: Update relevant docs if needed
- Be Constructive: Focus on code, not coder
- Explain Why: Provide reasoning for suggestions
- Suggest Solutions: Don't just point out problems
- Prioritize: Distinguish between blocking and non-blocking issues
- Learn Together: Use reviews as learning opportunities
- Self-Review First: Review your own PR before requesting review
- Small PRs: Keep changes focused and manageable
- Clear Descriptions: Explain what, why, and how
- Address Feedback: Respond to all review comments
- Test Thoroughly: Ensure everything works before requesting review
- MUST If you need to use mcp tools, remember to use sub-agents tall-pro to avoid main agent context flooding with big size of mcp response.
- Laravel Boost MCP Tools docs/Guidelines/LARAVEL_BOOST_GUIDELINES.md
Remember the following shortcuts which the user may invoke at any time.
When I type "qnew", this means:
Understand all BEST PRACTICES listed in CLAUDE.md and [Laravel Development Conventions](/docs/Guidelines/LARAVEL_DEVELOPMENT_CONVENTIONS.md).
Your code SHOULD ALWAYS follow these best practices.
When I type "qplan", this means:
Analyze similar parts of the codebase and determine whether your plan:
- is consistent with rest of codebase
- introduces minimal changes
- reuses existing code
When I type "qcode", this means:
Implement your plan and make sure your new tests pass.
Always run tests to make sure you didn't break anything else.
Always run `prettier` on the newly created files to ensure standard formatting.
Always run `./vendor/bin/pint --dirty` to make sure type checking and linting passes.
When I type "qux", this means:
Imagine you are a human UX tester of the feature you implemented.
Output a comprehensive list of scenarios you would test, sorted by highest priority.
When I type "qgit", this means:
Add all changes to staging, create a commit, and push to remote.
Follow this checklist for writing your commit message:
- SHOULD use Conventional Commits format: https://www.conventionalcommits.org/en/v1.0.0
- SHOULD NOT refer to Claude or Anthropic in the commit message.
- SHOULD structure commit message as follows:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
- commit SHOULD contain the following structural elements to communicate intent:
fix: a commit of the type fix patches a bug in your codebase (this correlates with PATCH in Semantic Versioning).
feat: a commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in Semantic Versioning).
BREAKING CHANGE: a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type.
types other than fix: and feat: are allowed, for example @commitlint/config-conventional (based on the Angular convention) recommends build:, chore:, ci:, docs:, style:, refactor:, perf:, test:, and others.
footers other than BREAKING CHANGE: <description> may be provided and follow a convention similar to git trailer format.
- docs/README.md - Complete project documentation overview with navigation
- docs/TABLE_OF_CONTENTS.md - Detailed table of contents for all documentation
- LARAVEL_PHP_GUIDELINES.md - Foundation: PHP/Laravel coding standards (PSR-12, typing, conventions)
- LARAVEL_DEVELOPMENT_CONVENTIONS.md - Project rules: TDD, testing, architecture patterns
- LARAVEL_BOOST_GUIDELINES.md - Workflow optimization: MCP tools, version-specific guidance
Integration Note: These three files work together as a layered approach - start with PHP standards, apply project conventions, then leverage Boost tools for optimal development experience.
- Start here: Quick Commands for common operations
- Follow guidelines: Implementation Best Practices - for best practices guidelines
- Check patterns: Architecture for consistency
- Plan first: Before Coding requirements
- Follow TDD: Testing approach
- Use shortcuts: QNEW/QPLAN/QCODE workflow
- Check existing: Browse docs/ folder first
- Follow structure: See TABLE_OF_CONTENTS.md