CLAUDE.md - Global Engineering Guidelines

About the Engineer

I am a senior WordPress engineer with baseline fluency across modern web development technologies. Assume competence, but be aware I may have missed recent API changes or new developments in any area.

Core Philosophy

Slow is Fast

Prioritize reasoning quality and maintainability over quick fixes. Take time to understand the problem fully before implementing solutions.

Simplicity is Elegance

The solution that achieves a goal with the least code is nearly always the best option. Avoid over-engineering, unnecessary abstractions, and premature optimization.

Code Quality Hierarchy (Maslow's Pyramid)

When reviewing or writing code, prioritize in this order:

Correct - Handles edge cases, no bugs
Secure - No vulnerabilities (OWASP top 10, injection, XSS, etc.)
Readable - Clear intent, self-documenting where possible
Elegant - Clean abstractions, DRY without over-abstraction
Altruistic - Considers future maintainers, well-documented

If code has issues at a lower level (correctness, security), address those before concerning yourself with style or elegance.

Reasoning & Planning

Task Analysis

Before any operation, analyze in this priority order:

Explicit rules and constraints from this file or project documentation
Operation sequencing and dependencies
Prerequisites and potential blockers
User preferences and project conventions

Task Complexity

Categorize tasks before starting:

Trivial: Single-step, obvious implementation. Execute directly.
Moderate: Multi-step but straightforward. Brief planning, then execute.
Complex: Multiple approaches, architectural impact, or unfamiliar territory. Enter Plan Mode.

Plan Mode / Code Mode Workflow

For complex tasks, explicitly switch between modes:

Plan Mode: Analysis and design

Announce: "Entering Plan Mode..."
Research existing code and patterns
Identify 1-3 potential approaches with tradeoffs
For projects with ADRs, consider drafting an ADR as the plan
Present plan for approval before implementation

Code Mode: Implementation

Announce: "Entering Code Mode..."
Implement the approved approach
Can re-enter Plan Mode for sub-problems within the larger implementation

Mode switching is fluid - feel free to switch into Plan Mode for details of a larger plan even when the overall structure has been decided.

Primary Tech Stack

Platforms

Altis DXP (default) - Enterprise WordPress platform by Human Made
WordPress VIP - Alternative enterprise platform (similar infrastructure, different CLI syntax)

Languages & Frameworks

PHP 8.2+ - Primary backend language
JavaScript (ES6+) - Frontend and block editor
React - WordPress block editor, admin interfaces
SCSS - Styling with PostCSS processing

Infrastructure

Elasticsearch - Search and content indexing
Redis - Object caching
AWS Services - Lambda (serverless functions), CloudFront (CDN)

Code Quality Tools

PHPCS with Human Made standards (HM-Minimum)
PHPStan Level 5
ESLint with WordPress rules
Stylelint for CSS/SCSS

Coding Standards

PHP Style (Human Made)

Architecture:

Prefer namespaced procedural code over unnecessary OOP abstractions
Use classes only when genuinely modeling objects or when the pattern benefits from encapsulation
Group code by feature, not by technology (e.g., Project\Reports not Project\CLI)

Bootstrap Pattern:

<?php
namespace Project\Feature;

function bootstrap() : void {
    add_action( 'init', __NAMESPACE__ . '\\register' );
    add_filter( 'the_content', __NAMESPACE__ . '\\filter_content' );
}

function register() : void {
    // Implementation
}

File Naming:

Main plugin file: plugin.php
Main theme file: functions.php
Classes: class-{classname}.php (lowercase)
Namespaced functions: namespace.php or {feature}.php
Top-level namespace directory: inc/

Conventions:

Array syntax: [] over array()
Yoda conditions: Not required
Visibility: Always declare public, protected, private; prefer protected over private
Type hints: Use for internal functions; exercise caution with WordPress callbacks that may pass unexpected types
Return types: Only declare when function returns exactly one type

Documentation:

Use imperative mood: "Display the date" not "Displays the date"
Add docblocks by default (linter requires them)
Strive for self-documenting code; add inline comments only where logic isn't self-evident

JavaScript Style

Modern JS (ES6+):

Prefer const over let; never use var
Use arrow functions for callbacks and context binding
Use destructuring and spread operators
Prefer functional programming (.map(), .filter()) over imperative loops

Conventions:

Trailing commas in multi-line arrays/objects
Semicolons end every statement
Avoid Yoda conditions
One class per file with export default

React Style

Use functional components with hooks for most cases
Semantic HTML5 elements; onClick only on focusable elements
Specify PropTypes for all component properties
Prefer props over state; avoid storing state in DOM
Co-locate styles and tests with components

CSS/SCSS Style

Use CSS custom properties via theme.json tokens where possible
BEM-like naming: .block--modifier, .block__element
Prefer theme.json styles over utility classes
kebab-case for class names

Local Development & Tooling

Altis Local Server (Default)

Altis projects use composer server commands for local development:

WP-CLI:

composer server cli -- <command>
# Example: composer server cli -- post list --post_type=page

Database Access:
# Get connection details
composer server db info

# Connect directly
composer server db

Running PHP Scripts:

# For complex operations, write a PHP file and execute it
composer server cli -- eval-file .claude/my-script.php

Fetching Pages:

Markup only: Use curl for static HTML inspection
Rendered/interactive: Use Playwright when you need JS execution or visual rendering

Logs:

composer server logs php

Debugging with Query Monitor: Query Monitor is available for runtime inspection. May require setting a cookie to display in responses - consult QM documentation for non-authenticated access.

Testing

Follow project conventions:

If the project has unit tests, consider test-first development for features of moderate to high complexity
Preferred frameworks: PHPUnit (PHP), Jest (JavaScript)
Ideally every project should have PHPUnit tests at minimum

Git & Version Control

User stays in the loop: Allow the engineer to:

Start branches from the correct base
Review all changes before committing
Write commit messages
Handle all git operations unless explicitly directed otherwise

Safe defaults:

Never rewrite history without explicit request
Explain any destructive operations beforehand
Never force push to main/master

Architecture Decision Records (ADRs)

For projects using ADRs:

Read existing ADRs to understand architectural intent
Draft an ADR as part of the planning phase for significant changes
ADRs document the "why" behind decisions for future maintainers

For new projects:

Suggest establishing an ADR practice
Create docs/architecture/ directory with initial ADR template

Response Format

Structure

Summary first, then supporting details
Bullet points for clarity, unless nuance requires prose
Provide context that led to conclusions rather than just stating conclusions

Code References

When referencing code, include file path and line number:

"The bootstrap function in inc/assets.php:15 handles asset enqueueing"

Mode Announcements

Explicitly announce mode transitions:

"Entering Plan Mode to analyze the authentication architecture..."
"Entering Code Mode to implement the approved approach..."

Context Management

Context represents working memory. For longer tasks:

Every ~10 responses: Refer back to the initial prompt to ensure we're still solving the original problem
Compact as you go: Discard information not essential to the current task
Summarize completed work: When finishing a phase, summarize what was accomplished before moving on
Flag scope creep: If the task has evolved significantly from the original request, pause and confirm direction

Error Handling

Proactive Fixes

Fix without asking:

Syntax errors
Linting violations
Type mismatches
Missing imports

Seek Confirmation

Ask before proceeding:

API changes that affect other code
Database migrations or schema changes
Destructive operations
Architectural decisions
Changes that deviate from the original plan

File Permissions

When creating new files in this project, ensure they have proper permissions:

Files: 644 (owner read/write, group/others read)
Directories: 755 (owner read/write/execute, group/others read/execute)

The web server needs to read project files. Files created with restrictive permissions (e.g., 400) will cause issues like patterns not being registered or includes failing silently.

After creating files, verify permissions with ls -la and fix if needed:

chmod 644 path/to/file.php

What Not To Do

Don't add features beyond what was requested
Don't refactor surrounding code unless asked
Don't add error handling for scenarios that can't happen
Don't create abstractions for one-time operations
Don't add documentation files unless explicitly requested
Don't make assumptions about git operations - let the engineer handle commits

goldenapples/CLAUDE.md

Select an option

No results found