# Clean Apex

> Clean-code focused Apex guidance for readability, naming conventions, 3-tier architecture (entry-point, static service, OO), error handling, and unit vs integration testing. Use when reviewing or generating Apex for clarity and maintainable structure, excluding security/performance scoring.

- Skill: `xixiaofinland/clean-apex` (Agent Skill, multi-file: 44 files)
- Install (CLI): `npx skillmds@latest add xixiaofinland/clean-apex`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xixiaofinland/clean-apex/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: xixiaofinland (https://skillmd.com/u/xixiaofinland)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xixiaofinland/clean-apex

---


# clean-apex

Provide opinionated, minimal clean-code guidance for Apex. Focus on readability, naming, architecture layering, error handling, and test separation. Avoid security checks, performance scoring, and broad best-practice audits unless explicitly requested.

## Load References

Read these files before doing any work:

- `references/naming-conventions.md`
- `references/architecture.md`
- `references/error-handling.md`
- `references/soql-di.md`
- `references/validator-exceptions.md`

## Quick Workflow

1. Clarify the task: review, generate, or both.
2. Identify the layer(s): entry-point, service, OO, or test.
3. Apply naming conventions from `references/naming-conventions.md`.
4. Enforce 3-tier responsibilities from `references/architecture.md`.
5. Apply error handling from `references/error-handling.md`.
6. Apply SOQL + DI constraints and test rules from `references/soql-di.md`.

## Generation Mode

When generating Apex:

- Use the 3-tier structure. Keep entry-point minimal; orchestrate in service; compute in OO.
- Put all DML in the static service layer only.
- Keep OO classes DML-free and focused on in-memory logic.
- Put SOQL in selector/query classes and inject into OO classes as properties.
- Follow naming conventions strictly.
- Avoid code comments unless they convey non-obvious intent or constraints that the code cannot express.
- Do not add auto-generated JavaDoc-style comments for classes or methods.
- Provide unit tests for OO classes with no DML; use DI to replace SOQL.
- Provide integration tests for entry-point/service behavior where DML is expected.

## How To Use Clean-Apex

Use this exact generation flow:

1. Read `templates/TEMPLATE_INDEX.md` and select layer-appropriate files.
2. Start from `CleanOrder*` templates in `templates/`, including async and trigger packs.
3. Run a sanitize check before final output and remove org-specific class names, object/field API names, IDs, endpoint domains, and business terms unless the user explicitly provides approved real names.

### Templates

Check `templates/TEMPLATE_INDEX.md` first to see which templates map to each layer/test type.
If templates exist at `templates/`, prefer them. If missing or incomplete, ask the user for sample Apex templates before generating full files.
Use `examples-sanitized/` for safe style references.

## Sanitization Rules

- Do not copy user-provided org-specific source snippets directly into generated output.
- Treat any org-specific source material as private pattern input only.
- Use generic class/object/field names in output unless the user explicitly provides org-specific names.
- Prefer standard objects or obvious placeholders in generated templates/examples.
- Before producing shareable code, ensure names and terms are masked and user-reviewed.

## Review Mode

When reviewing Apex:

- Flag naming violations with concrete rename suggestions.
- Flag layer violations (entry-point logic, service doing OO work, OO doing DML).
- Flag missing DI where OO relies on SOQL.
- Flag error handling that swallows exceptions without business justification.
- Flag OO tests that use DML or fail to mock SOQL.
- Flag unnecessary comments or auto-generated JavaDoc-style comments on classes/methods.
- Keep feedback concise and focused on readability and structure only.

## Error Handling Rules

- Let exceptions bubble to entry-point and handle there.
- Do not swallow exceptions unless business requirements demand it; log before swallowing.

## Testing Rules

- OO class unit tests must not use DML.
- When SOQL is required, inject a selector/query dependency to substitute the SOQL in tests.
- Use integration tests for entry-point/service flows that perform DML.

## Out of Scope

Do not add security checks, performance tuning, or scoring unless the user explicitly requests them.