# AEM review checklist, layer by layer

> **Verified:** 2026-09 against the sibling AEM skills in this catalog and https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/developing/development-guidelines

Run the sections that match the layers the diff touches. Report only findings; a clean section is not a comment.

## Security

- **HTL contexts.** `context='unsafe'` → **blocker**, always. `context='html'` is correct for a rich-text field (it runs the AntiSamy policy) and a **major** on a plain textfield or any author/user-supplied string that is not RTE output. `href`/`src` must keep the default `uri` context; values inside `<script>`, `<style>` or an event handler need `scriptString` / `styleString`.
- Java writing markup without `XSSAPI`; JSON built by string concatenation instead of a serialiser.
- Servlets bound with `sling.servlet.paths` (or `@SlingServletPaths`) → prefer a resource type with a selector and extension, so resource ACLs and dispatcher rules apply. For POST: method restriction and the Granite CSRF token.
- `loginAdministrative` or `getAdministrativeResourceResolver` → **blocker**. Service users come from repoinit, one sub-service per concern, least privilege, `with forced path system/cq:services/<proj>` and `set principal ACL`.
- Secrets, tokens or internal hostnames in `.cfg.json`, HTL or JS → `$[secret:]` / `$[env:]`.
- Dispatcher filters allowing broad paths (`/content/*`, bare `*.json`, `/bin/*`), `.infinity.json`, Query Builder, or `/allowedClients` changes. CDN rules that weaken authentication.
- Logging PII, tokens or whole request bodies.

## Resource handling

```java
try (ResourceResolver rr = factory.getServiceResourceResolver(
        Map.of(ResourceResolverFactory.SUBSERVICE, "content-reader"))) { … }
```

- A resolver from `ResourceResolverFactory` that is not closed → **blocker**.
- Never close `request.getResourceResolver()`; never store a resolver or `Session` in a field of a singleton.
- Streams from a `Rendition` or `Binary` closed; sessions you opened logged out.

## Performance

- Queries without a matching index, without `p.limit`, or computing exact totals on a large set. Ask for the query plan rather than guessing.
- Repository traversal or a query inside a render loop, especially in a model used in a list.
- Responses made uncacheable: `Set-Cookie` on a public page, per-user data in cached HTML, unbounded selectors or query strings, a JSON endpoint with no `Cache-Control`.
- Clientlibs: an all-in-one category on every page, un-minified vendor bundles, `embed` duplication, synchronous scripts in `<head>`, a lazy-loaded LCP image.

## Sling Models

- `adaptables` matches what the model needs (`SlingHttpServletRequest` for `currentPage`, `currentStyle`, WCMMode; `Resource` otherwise); `adapters` names an interface.
- `defaultInjectionStrategy = OPTIONAL` with null handling, or a deliberate required injection where absence is a bug. Injector-specific annotations over bare `@Inject`.
- Heavy work in `@PostConstruct`; getters cheap and side-effect free.
- The exporter does not leak internal fields, `Resource`, `Page` or `ValueMap`; `resourceType` set for component models.

## OSGi

- Configuration through `@Designate` + `@ObjectClassDefinition`; no Felix SCR annotations or `PropertiesUtil`.
- `@Reference` cardinality and policy deliberate; dynamic references `volatile`.
- Mutable instance state on a singleton service → thread-safety bug.
- Schedulers: `scheduler.concurrent=false`, `runOn` appropriate, and work that must happen once is a Sling Job instead.

## Components and dialogs

- Core Components extended by **proxy** (`sling:resourceSuperType`) and model **delegation**, never by copying a Core `*Impl` into `/apps`.
- Variants through content policies and the Style System, not a CSS-class field in the author dialog.
- Dialog field names (`name="./prop"`) match the model; `composite` on a multifield matches the Java injection; validation present where the field is required.
- Editable templates: allowed components come from the policy; responsive grid used correctly.

## Cloud Service compatibility

- Runtime writes to `/apps`, `/libs` or the file system; long-running threads; `System.exit`; custom replication agents; Classic UI; `/etc` lookups → **blocker**.
- Deprecated or removed APIs flagged by `aem-sdk-api` or the code-quality rules.
- Custom run modes, or an OSGi config in a folder that is not a supported run-mode combination (`author`, `publish`, `dev`, `stage`, `prod`, `rde`).

## Content packages and filters

- Package types correct: `application` for `/apps` and `/oak:index`, `content` for `/conf`, `/content`, `/home`. No mixed packages.
- `filter.xml` roots narrow. A default-mode (replace) filter on `/content/<site>` or `/conf/<site>` deletes authored content on every deploy → **blocker**. Author-owned roots use `mode="merge"`.
- Service users and ACLs come from repoinit, not `rep:policy` nodes in a package.
- Index definitions: `type="lucene"`, named `<prefix>.<name>-<productVersion>-custom-<n>` (for example `acme.article-1-custom-1`), with a matching `filter.xml` entry and a bumped version rather than an in-place edit. A name like `mysite-articles-custom-1` is rejected by the deploy gate. See `oak-index-naming.md` in `../../../development/aem-backend-development/references/`.

## Dispatcher and CDN

- Validated with `validate.sh`; filters deny-by-default with narrow structured allows (a `/url` glob needs a stated reason); cache rules and `/invalidate` scoped; `statfileslevel` matches the site depth; no redirect loops; explicit TTL headers.
- `cdn.yaml` traffic filter rules land in `log` action before `block`.

## Headless and Universal Editor

- Production GraphQL is persisted and called with `GET`; no ad-hoc `POST` from a browser.
- Persisted queries carry cache headers, and variable cardinality is low.
- CORS policy names explicit origins and `allowedpaths`; no `*` with credentials.
- No AEM token or author URL in a browser bundle.
- `data-aue-*` instrumentation is only in the editable/preview build, and its `data-aue-prop` values match real properties on the resource.
- A Content Fragment Model change is additive, and the affected persisted queries are listed.

## Edge Delivery Services PRs

EDS pull requests are reviewed against `aem-edge-delivery-services`, but these four belong in any review:

- Branch preview URLs (before and after) and the PageSpeed result are in the PR.
- `scripts/aem.js` is untouched.
- Every third-party script is in the delayed phase, and nothing contacts a second origin before LCP.
- The block decorates author content rather than rebuilding it from hard-coded strings.

## Tests and quality gates

- New logic has tests that assert behaviour, not just coverage; a bug fix has a regression test that fails without the fix.
- The change will not trip a Cloud Manager gate (coverage, SonarQube, OakPAL). Any suppression carries a justification comment.
- UI tests that produce no JUnit XML in `REPORTS_PATH` are reported as passing — check the reports exist.

## Accessibility and i18n

- Semantic markup, `alt` from asset metadata or the dialog, heading level configurable, keyboard-operable interactions, visible focus.
- User-facing strings through `${'…' @ i18n}` or a dictionary, with the dictionary entry actually added (a missing key silently renders the English source). `lang` attributes correct.

## Generated files

Generated clientlib folders, `dist` output and merged component JSON are build artefacts. If they are committed, check that the source changed too — and do not spend review time on their diffs.
