Claude Agent Guide

Guidance for Claude Code when collaborating on this repository.

📚 Required references

🛠️ Environment & setup

Provision the Python environment with
```
uv
```
: run
```
uv venv
```
, then
```
uv pip install -r requirements.txt
```
.

Start the API server with

uvicorn app.main:app --reload

uv run uvicorn app.main:app --reload

When Redis, Celery, or other infrastructure is required, consult
```
README.md
```
for service configuration details.

✅ Workflow expectations

Begin every session by reviewing
```
report/PROGRESS.md
```
,
```
report/summary/DIARY01.md
```
,
```
report/summary/DIARY02.md
```
,
```
report/summary/DIARY03.md
```
,
```
report/summary/DIARY04.md
```
,
```
report/summary/DIARY05_SUMMARY.md
```
, and
```
report/DIARY06.md
```
to capture current objectives and context.
- Lean on the summary files to refresh long-running context before diving into the detailed diary logs.
Study the applicable design documents and prompts before editing code to ensure that acceptance criteria and constraints are satisfied.
Follow strict test-driven development: introduce or update tests first, then implement code, and keep running
```
pytest
```
until the suite succeeds.
Close each session by updating
```
report/PROGRESS.md
```
and logging a new entry in
```
report/DIARY06.md
```
that summarizes the changes and decisions.

🔍 Review & prompt usage

When performing reviews, follow the prompts located in
```
instructions/prompts
```
, especially
```
02_codex_review_prompt.md
```
when coordinating with Codex outputs.
For implementation assignments, lean on guides such as
```
00_implementation_guide.md
```
and
```
01_backend_implementation_guide.md
```
to align with architectural expectations.

🧪 Testing & quality gates

Execute
```
pytest
```
to cover unit and integration paths, expanding scenarios in line with the documented test plan as needed.
Apply additional security or performance checks for sensitive changes, referencing the architecture and reinforcement learning design documents for specific criteria.

📏 Coding Standards

Grid Indexing Convention

In this project, we unify 2D grid indexing to row-major format:

Format:
```
grid[y][x]
```
or
```
grid[row][col]
```
Reason:
- Consistency with NumPy standard format
- Simplification of data exchange with frontend
- Consistency with mathematical matrix notation

Example:

# ✅ Correct
obstacles = [[False for _ in range(width)] for _ in range(height)]
if obstacles[y][x]:  # y=row, x=col
    ...

# ❌ Incorrect
obstacles = [[False for _ in range(height)] for _ in range(width)]
if obstacles[x][y]:
    ...

🛠️ Environment & setup

Provision the Python environment with

uv

: run

uv venv

, then

uv pip install -r requirements.txt

Start the API server with

uvicorn app.main:app --reload

uv run uvicorn app.main:app --reload

When Redis, Celery, or other infrastructure is required, consult

README.md

for service configuration details.

✅ Workflow expectations

Begin every session by reviewing

report/PROGRESS.md

report/summary/DIARY01.md

report/summary/DIARY02.md

report/summary/DIARY03.md

report/summary/DIARY04.md

report/summary/DIARY05_SUMMARY.md

, and

report/DIARY06.md

to capture current objectives and context.

Lean on the summary files to refresh long-running context before diving into the detailed diary logs.

Study the applicable design documents and prompts before editing code to ensure that acceptance criteria and constraints are satisfied.

Follow strict test-driven development: introduce or update tests first, then implement code, and keep running

pytest

until the suite succeeds.

Close each session by updating

report/PROGRESS.md

and logging a new entry in

report/DIARY06.md

that summarizes the changes and decisions.

🔍 Review & prompt usage

When performing reviews, follow the prompts located in

instructions/prompts

, especially

02_codex_review_prompt.md

when coordinating with Codex outputs.

For implementation assignments, lean on guides such as

00_implementation_guide.md

and

01_backend_implementation_guide.md

to align with architectural expectations.

📏 Coding Standards

In this project, we unify 2D grid indexing to row-major format:

Format:

grid[y][x]

grid[row][col]

Reason:

Consistency with NumPy standard format
Simplification of data exchange with frontend
Consistency with mathematical matrix notation

Example:

# ✅ Correct
obstacles = [[False for _ in range(width)] for _ in range(height)]
if obstacles[y][x]:  # y=row, x=col
    ...

# ❌ Incorrect
obstacles = [[False for _ in range(height)] for _ in range(width)]
if obstacles[x][y]:
    ...

Claude Agent Guide

Claude Agent Guide

📚 Required references

🛠️ Environment & setup

✅ Workflow expectations

🔍 Review & prompt usage

🧪 Testing & quality gates

📏 Coding Standards

Grid Indexing Convention

Related Skills

Markdown Converter

Nano Banana Pro

1password

Claude Agent Guide

📚 Required references

🛠️ Environment & setup

✅ Workflow expectations

🔍 Review & prompt usage

🧪 Testing & quality gates

📏 Coding Standards

Grid Indexing Convention