Org Skills

AEM review checklist, layer by layer

Supporting material for aem-code-review. Agents load it on demand; it ships inside the skill folder.

RawSource

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

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.