open-swe/docs/repo-conventions/AGENTS.md.sam

# AGENTS.md — SAM conventions

Supplement to `AGENTS.md.aws`. Merge into the repo root `AGENTS.md` alongside
the AWS base conventions.

## Directory layout

```
.
├── template.yaml              # SAM template (single-file or entrypoint)
├── .aws-sam/                  # SAM build artifacts (git-ignored)
├── src/
│   └── <function-name>/
│       ├── app.py             # Lambda handler
│       └── requirements.txt   # Per-function dependencies
├── layers/
│   └── <layer-name>/
│       ├── requirements.txt
│       └── (source files)
├── events/                    # Test event payloads
├── samconfig.toml             # SAM CLI configuration
└── Makefile                   # Build/deploy shortcuts
```

## Layer `BuildMethod` nesting gotcha

When a Lambda layer's `ContentUri` points to a directory that contains a
`requirements.txt`, SAM's `python3.12` build method nests the installed
packages under `python/` inside the layer. Do **not** create an extra
`python/` directory inside the layer source — let SAM handle it. That is:

```
# Correct — SAM creates python/ for you
MyLayer:
  Type: AWS::Serverless::LayerVersion
  Properties:
    ContentUri: layers/my-layer/
    CompatibleRuntimes: [python3.12]
  Metadata:
    BuildMethod: python3.12

# Wrong — double-nesting breaks imports
MyLayer:
  ...
    ContentUri: layers/my-layer/python/  # DON'T do this
```

## Build & validate

```bash
sam build              # Build all functions and layers
sam validate           # Validate the template
sam local invoke ...   # Test a single function locally
```

- Run `sam build && sam validate` before pushing. Do not commit `.aws-sam/`.
- If the repo has a `Makefile` wrapping these, use the Makefile targets.