diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..327fd3a
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,42 @@
+# AGENTS.md
+
+Guidance for coding agents working in `github.com/sourcegraph/go-jsonschema`, an
+**experimental** Go library for reading JSON Schema (draft-07) documents and
+generating Go types from them.
+
+## Layout
+
+- `jsonschema/` — core library: schema types, parsing, walking, URI handling.
+- `compiler/` — generates Go source from JSON Schemas (parser, resolver,
+  generators); golden-file fixtures live in `compiler/testdata/`.
+- `cmd/go-jsonschema-compiler/` — CLI that emits Go types from schema files.
+- `internal/` — test helpers (`testutil`) and the official JSON Schema test
+  suite runner (`jsonschematestsuite`).
+- `testdata/` — shared schema fixtures (e.g. the draft-07 meta-schema).
+
+## Setup
+
+The official test suite is vendored as a git submodule. After cloning, run:
+
+```sh
+git submodule update --init --recursive
+```
+
+## Build, test, run
+
+```sh
+go run ./cmd/go-jsonschema-compiler -pkg schema -o out.go schema.json
+```
+
+The CLI accepts one or more JSON Schema files; `-pkg` sets the emitted package
+name and `-o` writes to a file instead of stdout.
+
+## Conventions
+
+- Standard Go formatting (`gofmt`); generated output is run through
+  `go/format`.
+- Compiler tests are golden-file based: each `compiler/testdata/<case>/` holds a
+  `schema.json` input and a `want.go` expected output. Update the corresponding
+  `want.go` when intentionally changing generated code.
+- CI (`.github/workflows/go-ci.yml`) checks out submodules recursively and runs
+  `go test ./...`; keep that command green.