diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..2740029b
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,57 @@
+# AGENTS.md — commit-analyzer
+
+> Clearcover's fork of `@semantic-release/commit-analyzer`: a semantic-release plugin that parses git commits using conventional-changelog conventions and returns the appropriate release type (major / minor / patch / null).
+
+## Quick start
+
+```bash
+# Install
+npm install
+
+# Test — must pass before every PR (runs lint first via pretest, then ava with coverage)
+npm test
+
+# Lint only
+npm run lint
+```
+
+## Domain position
+
+**Layer:** Shared Services — developer tooling / CI-CD infrastructure
+**Domain:** Analytics Domain (closest fit; this is a cross-cutting build tool, not a runtime service)
+
+**This service owns:**
+- Release-type determination logic for Clearcover's semantic-release pipelines
+
+**Observed callers:** consumed as a semantic-release plugin in other Clearcover repos' CI configs
+**Observed dependencies:** `conventional-commits-parser`, `conventional-commits-filter`, `conventional-changelog-angular`, `debug`, `import-from`, `lodash`
+
+> Absence means not observed in this scan, not that the integration doesn't exist.
+
+## Tech stack
+
+- **Language/runtime:** Node.js >=8.3
+- **Test:** ava (via `nyc ava -v`; coverage collected by nyc)
+- **Lint:** xo (with prettier, printWidth 120)
+
+## Project structure
+
+```
+index.js              — plugin entry point; exports analyzeCommits()
+lib/
+  analyze-commit.js       — matches a single commit against release rules
+  compare-release-types.js — orders major > minor > patch
+  default-release-rules.js — built-in rule set
+  default-release-types.js — ordered list of release type strings
+  load-parser-config.js    — resolves conventional-changelog preset/config
+  load-release-rules.js    — loads and validates custom release rules from plugin config
+test/                 — ava test files + fixtures
+```
+
+## Boundaries
+
+**Always:** run `npm test` before pushing · respect domain boundaries above · no secrets in commits
+**Ask first:** changes to default release rules (affects all consuming repos) · new external deps · peer dependency version bumps
+**Never:** push to master · skip failing tests · modify release type ordering without understanding downstream impact
+
+> ⚠️ Auto-generated by AI agent and audited against actual repo files at generation time. Review and update when this repo next changes.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..43c994c2
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md