diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..23cb7c0
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,27 @@
+This file provides guidance to AI coding agents when working with code in this repository.
+
+## What this project is
+
+`singed` makes it easy to get a flamegraph anywhere in a Ruby codebase. It wraps profiling with [stackprof](https://github.com/tmm1/stackprof) or [rbspy](https://github.com/rbspy/rbspy) and launches [speedscope](https://github.com/jlfwong/speedscope) to view results.
+
+## Commands
+
+```bash
+bundle install
+
+# Run all tests (RSpec)
+bundle exec rspec
+
+# Run a single spec file
+bundle exec rspec spec/path/to/spec.rb
+
+# Lint
+bundle exec rubocop
+bundle exec rubocop -a  # auto-correct
+```
+
+## Architecture
+
+- `lib/singed.rb` — main entry point; provides `Singed.flamegraph` block helper
+- `lib/singed/` — core classes: flamegraph output handling, stackprof/rbspy integrations, speedscope launcher
+- `spec/` — RSpec tests
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..43c994c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md