diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..da57839
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,49 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+- Root: `manifest.json`, `package.json` (when added), config files.
+- `src/`: extension code.
+  - `background/`: RPC, messaging, and long‑lived tasks.
+  - `content/`: archive.org DOM parsing on `/download/*` pages.
+  - `popup/` and `options/`: UI, settings, and actions.
+  - `lib/`: shared utils (filters, size/date parsing, aria2 client).
+- `assets/`: icons and static resources.
+- `tests/`: unit (`tests/unit`) and e2e (`tests/e2e`).
+- Note: initial repo is docs-first; scaffolding will create these paths.
+
+## Build, Test, and Development Commands
+
+- Install: `npm install` (after `package.json` lands).
+- Dev (Firefox): `npx web-ext run --source-dir .` or `npm run dev`.
+- Build: `npx web-ext build -o -a dist` or `npm run build` → `dist/`.
+- Lint/Format: `npm run lint` and `npm run format`.
+- Tests: `npm test` (Jest). E2E via Playwright: `npm run test:e2e`.
+
+## Coding Style & Naming Conventions
+
+- Language: JavaScript (ES2020+) or TypeScript (preferred for new modules).
+- Indentation: 2 spaces; max line length 100; use semicolons.
+- Filenames: kebab-case (`filters-utils.ts`, `aria2-client.ts`). UI components: PascalCase.
+- Identifiers: camelCase; UPPER_SNAKE_CASE for constants; verbs for functions.
+- Tools: ESLint + Prettier. Run `npm run lint` before pushing.
+
+## Testing Guidelines
+
+- Framework: Jest for unit tests; Playwright for e2e (popup/content behaviors).
+- Location: unit under `tests/unit/**/*.spec.(js|ts)`; e2e under `tests/e2e/**`.
+- Coverage: target ≥ 80% lines for core filters and RPC client.
+- Focus: filename/type regex, size/date filters, clipboard, and `aria2.addUri` payloads.
+
+## Commit & Pull Request Guidelines
+
+- Commits: Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`). Use imperative mood.
+- PRs: concise description, motivation, screenshots/GIFs for UI, test plan, and linked issues.
+- Scope: keep PRs small and focused; update docs when behavior changes.
+
+## Security & Configuration Tips
+
+- Do not commit secrets. Store aria2 RPC token in `browser.storage.local`.
+- Prefer HTTPS for remote RPC; if self-signed, document trust steps locally only.
+- Provide examples as `config.example.json`; ignore local overrides in `.gitignore`.
+