diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..6a5c4b3
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,97 @@
+# AGENTS.md
+
+## Project Overview
+
+- This repository is a Go service named `epic-ent`.
+- The application uses `go.uber.org/fx` for dependency injection and lifecycle management.
+- HTTP is served with `github.com/labstack/echo/v4`.
+- Configuration is loaded by `viper` from `application.yaml` in the repository root.
+- Persistence uses MySQL plus `ent` ORM/codegen; Redis and cron infrastructure are also wired in.
+
+## High-Value Architecture Notes
+
+- Main entrypoint: `cmd/server/main.go`
+- App composition root: `internal/bootstrap/app.go`
+- Config loading: `internal/config/config.go`
+- HTTP server bootstrap: `internal/infra/http/http.go`
+- Ent client bootstrap: `internal/infra/db/ent.go`
+- Shared response envelope: `internal/domain/vo/response.go`
+
+Current dependency flow follows this pattern:
+
+1. `controller` handles HTTP binding and response shaping.
+2. `service` contains business defaults/orchestration.
+3. `repository` talks to `ent` and database models.
+4. `infra` provides framework/runtime dependencies.
+
+For feature work, preserve this layering unless the user explicitly asks for a refactor.
+
+## Directory Guide
+
+- `cmd/server`: production app entrypoint.
+- `cmd/gen/controllers`: generator for `internal/controller/module.go`.
+- `db/schema.sql`: database schema reference.
+- `internal/bootstrap`: top-level Fx wiring.
+- `internal/config`: configuration structs and module wiring.
+- `internal/controller`: Echo handlers and route registration.
+- `internal/domain/dto`: request DTOs.
+- `internal/domain/vo`: response/output view objects.
+- `internal/domain/entity`: domain entity definitions related to schema.
+- `internal/repository`: data access using `ent.Client`.
+- `internal/service`: business service layer.
+- `internal/infra`: logger, DB, Redis, HTTP, cron providers.
+- `internal/ent`: generated Ent ORM code.
+
+## Generated Code Rules
+
+- Treat `internal/ent/**` as generated code unless the user explicitly requests regeneration-related work.
+- Do not hand-edit generated Ent files as a first choice.
+- `internal/controller/module.go` is generated by `cmd/gen/controllers/main.go`.
+- If controller constructors change, prefer regenerating `internal/controller/module.go` through the generator instead of manually maintaining it.
+
+## Editing Rules For Codex
+
+- Keep changes minimal and consistent with existing Go style.
+- Prefer extending existing `controller -> service -> repository` patterns over introducing new abstractions.
+- Reuse existing response helpers such as `vo.OK(...)` and related error handling patterns.
+- When adding HTTP endpoints, update route registration in `internal/controller/routes.go` and keep handler behavior aligned with current Echo patterns.
+- When changing persistence behavior, inspect corresponding DTO/VO/repository/service flow together to avoid partial changes.
+- Avoid broad refactors unless they are required to solve the requested task.
+
+## Config And Secrets
+
+- `application.yaml` currently contains real-looking database and Redis credentials.
+- Do not print, duplicate, or move those secrets into additional files.
+- If config changes are required, prefer structure-preserving edits and avoid exposing credential values in summaries.
+- If the user asks for security hardening, a strong candidate improvement is migrating secrets out of the committed config and into environment variables or untracked local config.
+
+## Known Runtime Conventions
+
+- The HTTP server port and read/write timeouts come from `application.yaml`.
+- The server is started through Fx lifecycle hooks, not directly in `main`.
+- Repository methods use soft delete semantics for heroes via `deleted = false/true` filtering and updates.
+- Current API examples in `internal/controller` expose CRUD-style `/heroes` routes.
+
+## Validation Guidance
+
+When verifying changes, prefer the smallest useful command first:
+
+- `go test ./...`
+- `go build ./cmd/server`
+- If generator-related files changed, also run the relevant generator command before testing.
+
+Run validation from the repository root: `epic-ent`.
+
+## Safe Default Workflow
+
+1. Read the affected entrypoint/module/wiring before editing.
+2. Check whether the target file is generated.
+3. Make focused changes in the appropriate layer.
+4. Validate with targeted `go test` or `go build` when feasible.
+5. Summarize changed files and any remaining risks.
+
+## Current Observations
+
+- The repository appears to focus on Epic Seven-related data entities, with `hero` currently being the clearest implemented end-to-end example.
+- There may be more entities already represented in `internal/ent` and `internal/domain/entity` than are currently exposed via controllers/services.
+- Because Ent code is already generated for multiple tables, schema-driven changes may require coordinated updates rather than isolated handler edits.