Here is the base of my .claude/CLAUDE.md file for when I am using Claude Cowork for development.
## About Me
- **Role**: Web Developer, Systems Administrator, and Team Lead at WordPress VIP (wpvip.com / Automattic)
- I work primarily in PHP (WordPress), JavaScript/TypeScript, and Bash
- I have a deep technical background and prefer direct, technically precise communication
- I'm a team lead, so I often need output that is clear and explainable to others
---
## General Coding Preferences
- Use **modern, clean, readable code** — clarity wins over cleverness
- Prefer **explicit over implicit** — no magic unless well-documented
- Always write **defensive code**: validate inputs, handle edge cases, fail gracefully
- Avoid unnecessary abstractions; solve the actual problem
- When in doubt, follow the **principle of least surprise**
- Prefer `const` over `let`; avoid `var` entirely
- Use **async/await** over raw promises or callbacks when possible
---
## WordPress / WordPress VIP Conventions
- Follow the [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/)
- Follow [VIP Coding Standards](https://docs.wpvip.com/how-tos/php_codesniffer/) — these are stricter than core WP standards
- **Never** use `$wpdb->query()` for data-modifying queries without prepared statements
- **Never** use `echo` for direct output in templates — use `esc_html()`, `esc_attr()`, `wp_kses_post()`, etc.
- Prefer `wp_remote_get()` / `wp_remote_post()` over raw `curl` or `file_get_contents()`
- Avoid direct database queries when WP APIs exist (`WP_Query`, `get_posts()`, etc.)
- Use **object caching** (`wp_cache_get` / `wp_cache_set`) for expensive queries
- Hooks over direct calls: prefer `add_action` / `add_filter` patterns
- **No** direct file writes (`file_put_contents`, `fopen`, etc.) — use WP filesystem API
- Prefix all custom functions, hooks, and globals with the project namespace
- Avoid `exit()` / `die()` outside of AJAX handlers — and even then, prefer `wp_send_json()`
---
## JavaScript / TypeScript Preferences
- Use **TypeScript** when the project supports it
- Follow the [Automattic/VIP JavaScript standards](https://github.com/Automattic/eslint-config-wpvip) if present
- Use `@wordpress/scripts` tooling when building WordPress blocks or admin UI
- Prefer **functional components** with hooks over class components in React
- Always handle loading, error, and empty states in UI components
---
## Dev Workflow
- **Always lint before suggesting a commit**: run PHPCS and/or ESLint
- Assume the project uses **Git Flow** or feature branches unless told otherwise
- Commit messages should follow [Conventional Commits](https://www.conventionalcommits.org/):
- `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`
- Keep the subject line under 72 characters
- Use the body to explain *why*, not just *what*
- Prefer **small, focused PRs** — one logical change per PR
- PRs should include a description of what changed and why
- If writing tests, use **PHPUnit** for PHP and **Jest** for JavaScript
---
## Team & Communication Style
- I lead a team, so when writing docs, PR descriptions, or comments: write for the team, not just for me
- Keep explanations clear and jargon-free enough for mid-level developers
- Flag anything that could be a **performance**, **security**, or **scalability** concern — I'd rather know
- If something I'm doing is non-standard or could cause issues at scale (VIP hosts high-traffic sites), say so
---
## What I Don't Need
- Don't explain basic WordPress or PHP concepts unless I ask
- Don't add unnecessary inline comments for obvious code
- Don't pad responses with filler — get to the point
- Don't add linting/formatting rules in this file — my project configs handle that
---
## Misc Preferences
- When creating files, use `.md` for documentation, `.ts` for new scripts when possible
- Prefer named exports over default exports in modules
- When writing shell scripts, use `#!/usr/bin/env bash` and `set -euo pipefail`
- I use macOS as my primary dev machine; assume UNIX-compatible commandsShare
