add AGENTS.md

Add AGENTS.md to allow AI assistants to be more effective, especially
the Code Review Bot.

Note: do not create .github/copilot-instructions.md as it will prevent
current version of Copilot CLI from reading AGENTS.md at all.

Signed-off-by: Tuomo Tanskanen <[email protected]>

Author: tuminoid

.gitignore

@@ -35,3 +35,6 @@ out
 *~
 *.tmp
 .DS_Store
+
+# ai stuff
+.claude

.markdownlint-cli2.yaml

@@ -5,6 +5,7 @@ config:
     # Kramdown wanted us to have 3 earlier, tho this CLI recommends 2 or 4
     indent: 3
   line-length:
+    # Ignore long lines in tables and code blocks
     tables: false
     code_blocks: false
 

AGENTS.md

@@ -0,0 +1,103 @@
+# Metal3 IP Address Manager - AI Agent Instructions
+
+Instructions for AI coding agents. For project overview, see [README.md](README.md).
+For contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Repository Structure
+
+| Directory | Purpose |
+|-----------|---------|
+| `api/v1alpha1/` | CRD types (IPPool, IPClaim, IPAddress) - separate Go module |
+| `controllers/` | Reconciliation logic |
+| `ipam/` | Core IP allocation algorithms |
+| `internal/webhooks/` | Validation/defaulting webhooks |
+| `config/` | Kustomize manifests (CRDs, RBAC, webhooks) - auto-generated by `make generate`, rarely edit directly |
+| `hack/` | CI scripts (prefer Make targets locally) |
+
+## Testing Standards
+
+CI is managed by [Prow](https://github.com/metal3-io/project-infra/blob/main/prow/config/jobs/metal3-io/ip-address-manager.yaml).
+Run these locally before submitting PRs:
+
+**Make targets:**
+
+| Command | Purpose |
+|---------|---------|
+| `make test` | Full verification (generate + lint + unit) |
+| `make generate` | Regenerate code (DeepCopy, CRDs, RBAC, mocks) |
+| `make unit` | Unit tests (requires envtest - do not use `go test` directly) |
+| `make lint` | Go linting via golangci-lint (all modules) |
+| `make verify-boilerplate` | Check license headers |
+| `make modules` | Verify go.mod is tidy |
+
+**Hack scripts** (auto-containerized, match CI exactly):
+
+| Script | Purpose |
+|--------|---------|
+| `./hack/shellcheck.sh` | Shell script linting (shellcheck) |
+| `./hack/markdownlint.sh` | Markdown linting (config: `.markdownlint-cli2.yaml`) |
+| `./hack/manifestlint.sh` | Kubernetes manifest validation (kubeconform) |
+
+**GitHub Actions** (reusable workflows from project-infra):
+
+| Workflow | Purpose |
+|----------|---------|
+| yamllint | YAML linting (config: `.yamllint.yaml`) |
+
+## Code Conventions
+
+- **Go**: Linting rules in `.golangci.yaml`, license headers in `hack/boilerplate/`
+- **Shell**: Use `set -o errexit -o nounset -o pipefail`
+- **Markdown**: 3-space indent for lists (`.markdownlint-cli2.yaml`)
+
+## Key Workflows
+
+### Modifying APIs
+
+1. Edit `api/v1alpha1/*_types.go`
+1. Run `make generate`
+1. Update webhooks in `internal/webhooks/` if validation changes
+1. Run `make test`
+
+## Code Review Guidelines
+
+When reviewing pull requests:
+
+1. **Security** - Hardcoded secrets, unpinned dependencies, missing input validation
+1. **Test coverage** - New functionality should have tests
+1. **Consistency** - Match existing patterns in the codebase
+1. **Breaking changes** - Flag API/behavior changes affecting users
+
+Focus on: `controllers/`, `ipam/`, `api/`, `internal/webhooks/`.
+
+## AI Agent Guidelines
+
+### Before Changes
+
+1. Run `make unit` to verify baseline
+1. Check patterns in similar existing files
+
+### When Making Changes
+
+1. Make minimal, surgical edits
+1. Run `make generate` after API changes
+1. Run `make test` before committing
+1. Add tests for new functionality
+
+### Security Requirements
+
+- Pin external dependencies by SHA (containers, GitHub Actions, binaries)
+- No hardcoded credentials
+- Validate all inputs
+
+## E2E Testing
+
+IPAM has no standalone e2e tests. E2E runs through
+[CAPM3](https://github.com/metal3-io/cluster-api-provider-metal3).
+
+## Related Documentation
+
+- [API Documentation](docs/api.md)
+- [Testing Guide](docs/testing.md)
+- [Release Process](docs/releasing.md)
+- [Metal3 Book](https://book.metal3.io/ipam/introduction)

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md