CLAUDE.md.template

# CLAUDE.md Template for WordPress Projects

> **Platform**: Claude Code
> **Purpose**: Project-specific instructions for Claude Code
> **Usage**: Copy to your project root as `CLAUDE.md`

## Instructions

Copy this file to your WordPress plugin/theme project root and customize the placeholders.

---

# CLAUDE.md

## Project Overview

**Project**: [PROJECT_NAME]
**Type**: WordPress [plugin/theme/block-theme]
**Slug**: [project-slug]
**Text Domain**: [text-domain]
**Prefix**: [prefix_]
**Minimum WordPress**: 6.9
**Minimum PHP**: 8.2

## Development Standards

### WordPress Coding Standards

- Follow [WordPress PHP Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/)
- Follow [WordPress JavaScript Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/)
- Use tabs for indentation (PHP and JS)
- Use Yoda conditions: `if ( 'value' === $var )`

### Naming Conventions

- Functions: `[prefix_]function_name`
- Classes: `[Prefix_]Class_Name` or `[Prefix]\Namespace\ClassName` (PSR-4)
- Constants: `[PREFIX_]CONSTANT_NAME`
- Hooks: `[prefix_]/hook-name` or `[prefix_]_hook_name`
- Options: `[prefix_]_option_name`

### Security Requirements (the Security Trinity)

**Sanitize input** — every value from `$_GET`, `$_POST`, `$_REQUEST`:
- `sanitize_text_field()`, `absint()`, `sanitize_email()`, `wp_kses_post()`

**Validate data** — confirm it matches expectations:
- Nonces: `wp_verify_nonce()` or `check_admin_referer()`
- Capabilities: `current_user_can()` before any protected action
- Allowlists: `in_array( $val, $allowed, true )`

**Escape output** — at the point of rendering:
- `esc_html()`, `esc_attr()`, `esc_url()`, `wp_kses_post()`
- SQL: `$wpdb->prepare()` with `%s`, `%d`, `%f` placeholders

### i18n Requirements

- Wrap all user-facing strings in translation functions
- Text domain: `[text-domain]`
- Include translator comments for strings with placeholders

```php
__( 'Text', '[text-domain]' );
/* translators: %s: user name */
sprintf( __( 'Hello, %s', '[text-domain]' ), $name );
```

## File Structure

```
[project-slug]/
├── [project-slug].php      # Main plugin file
├── includes/               # PHP classes
├── src/                    # Block source / JS source
├── build/                  # Compiled assets (gitignored)
├── assets/                 # Static assets (images, fonts)
├── languages/              # Translation files
├── templates/              # Template files
├── tests/
│   ├── Unit/               # Brain\Monkey unit tests
│   └── Integration/        # WP_UnitTestCase integration tests
├── uninstall.php           # Cleanup on uninstall
├── readme.txt              # WordPress.org readme
└── composer.json
```

## Build Commands

```bash
composer install && npm install    # Dependencies
npm run start                      # Watch mode
npm run build                      # Production build
composer test                      # PHPUnit
composer lint                      # PHPCS (WordPress-Extra)
composer analyze                   # PHPStan level 6
npm run lint:js                    # ESLint
npm run test:unit                  # Jest
npm run env:start                  # Start wp-env
```

## Testing

- PHPUnit with `yoast/phpunit-polyfills` for all public methods
- PHPCS with `WordPress-Extra` ruleset
- PHPStan level 6 with `szepeviktor/phpstan-wordpress`
- Jest for JavaScript components
- Playwright E2E for critical user flows

## Project-Specific Notes

[Add project-specific instructions, gotchas, or important context here]

## External Dependencies

[List external services, APIs, or dependencies with docs links]