AGENTS

Baseline rules for changes in this repository.

Development Rules (Checklist)

If you modify Go files, run
```
gofmt -w <files>
```
(or
```
gofmt -w .
```
to format everything).
After changes, run
```
go vet ./...
```
and confirm there are no errors.
After changes, run
```
go test ./...
```
and confirm there are no errors.
After changes, run
```
go test -race ./...
```
and confirm there are no errors.
Before opening a PR, verify generated-file drift checks stay clean:
```
go mod tidy
```
,
```
go generate ./...
```
, and
```
git diff --exit-code
```
.

If dependencies changed (

go.mod

go.sum

), run

bash scripts/gen-third-party-notices.sh

and ensure no drift in

THIRD_PARTY_NOTICES.md

Before implementation, create (or confirm) a GitHub Issue that tracks the work.
Keep issue scope atomic: one issue must map to one fix or one feature.
Use short-lived branches (e.g.
```
feature/*
```
) and merge via PR using squash merge; do not commit directly to
```
master
```
unless explicitly requested.
Implement only on the issue branch and merge via PR; never push implementation commits directly to
```
master
```
.
Use the
```
branch-helper
```
skill for tasks that modify the repository unless the user requests otherwise.
After addressing review feedback, ask Codex for a re-review in chat.
PRs must include an auto-close keyword for related issues (e.g.
```
Closes #123
```
).
PR bodies must be based on
```
.github/PULL_REQUEST_TEMPLATE.md
```
and keep all sections.
When creating PRs with
```
gh
```
, always use
```
--body-file
```
from the template (avoid
```
--fill
```
alone).
Create the PR right after the initial implementation commit so fix logs can be tracked in the PR body.
Maintain a running fix log in the PR body after each correction pass.
When editing PR bodies with
```
gh
```
, use
```
-F <file>
```
and rewrite the full body (no
```
--add-body
```
flag exists).
For implementation work, always follow this flow: Implement → Test → Review.
- If the review has findings, ask numbered questions for any confirmations needed.
- Once confirmations are resolved, apply fixes and repeat Fix → Test → Review until there are no findings.

Workflow Notes

Keep tests deterministic; avoid time-based ordering and use controllable IO (e.g. pipes) when sequencing matters.
When mocking the niconico API, ensure pagination terminates (e.g. return empty items or 404 for page > 1).
Avoid interactive editors in automated merges (use
```
gh pr merge --squash
```
and set
```
GIT_EDITOR
```
to a non-interactive command when needed).
Before merging, wait for all CI checks to complete (use
```
gh pr checks --watch
```
) unless explicitly told to skip.
When handling multiple pull requests, create all PRs first, then run CI confirmation and merge operations together at the end.
When a versioned milestone is completed, release using the same version number; after the release workflow succeeds, close the milestone.
```
master
```
is protected by repository rulesets: PR-only updates, required conversation resolution, required
```
go-ci
```
, and squash-only merge method.
Release tags (
```
refs/tags/v*
```
) are protected by repository rulesets that control tag create/update/delete operations.

Improvements / Backlog

Keep

docs/DESIGN.md

focused on the current, agreed-upon behavior. Do not add undecided proposals to

docs/DESIGN.md

. Record undecided proposals and improvement ideas in GitHub Issues.

Dependencies

Ask for approval before adding new runtime (production) dependencies.

When a review has findings, always ask confirmation questions for all findings. Do not implement changes related to those findings until answers are received. Number each question to make responses easier.

Documentation Language

Keep

README.md

docs/DESIGN.md

, and

AGENTS.md

in English.

Development Rules (Checklist)

If you modify Go files, run

gofmt -w <files>

(or

gofmt -w .

to format everything).

After changes, run

go vet ./...

and confirm there are no errors.

After changes, run

go test ./...

and confirm there are no errors.

After changes, run

go test -race ./...

and confirm there are no errors.

Before opening a PR, verify generated-file drift checks stay clean:

go mod tidy

go generate ./...

, and

git diff --exit-code

If dependencies changed (

go.mod

go.sum

), run

bash scripts/gen-third-party-notices.sh

and ensure no drift in

THIRD_PARTY_NOTICES.md

Before implementation, create (or confirm) a GitHub Issue that tracks the work.

Keep issue scope atomic: one issue must map to one fix or one feature.

Use short-lived branches (e.g.

feature/*

) and merge via PR using squash merge; do not commit directly to

master

unless explicitly requested.

Implement only on the issue branch and merge via PR; never push implementation commits directly to

master

Use the

branch-helper

skill for tasks that modify the repository unless the user requests otherwise.

After addressing review feedback, ask Codex for a re-review in chat.

PRs must include an auto-close keyword for related issues (e.g.

Closes #123

PR bodies must be based on

.github/PULL_REQUEST_TEMPLATE.md

and keep all sections.

When creating PRs with

gh

, always use

--body-file

from the template (avoid

--fill

alone).

Create the PR right after the initial implementation commit so fix logs can be tracked in the PR body.

Maintain a running fix log in the PR body after each correction pass.

When editing PR bodies with

gh

, use

-F <file>

and rewrite the full body (no

--add-body

flag exists).

For implementation work, always follow this flow: Implement → Test → Review.

If the review has findings, ask numbered questions for any confirmations needed.
Once confirmations are resolved, apply fixes and repeat Fix → Test → Review until there are no findings.

Workflow Notes

Keep tests deterministic; avoid time-based ordering and use controllable IO (e.g. pipes) when sequencing matters.

When mocking the niconico API, ensure pagination terminates (e.g. return empty items or 404 for page > 1).

Avoid interactive editors in automated merges (use

gh pr merge --squash

and set

GIT_EDITOR

to a non-interactive command when needed).

Before merging, wait for all CI checks to complete (use

gh pr checks --watch

) unless explicitly told to skip.

When handling multiple pull requests, create all PRs first, then run CI confirmation and merge operations together at the end.

When a versioned milestone is completed, release using the same version number; after the release workflow succeeds, close the milestone.

master

is protected by repository rulesets: PR-only updates, required conversation resolution, required

go-ci

, and squash-only merge method.

Release tags (

refs/tags/v*

) are protected by repository rulesets that control tag create/update/delete operations.

AGENTS

AGENTS

Development Rules (Checklist)

Workflow Notes

Design

Improvements / Backlog

Work Log

Dependencies

Review Questions

Documentation Language

Related Skills

Markdown Converter

Nano Banana Pro

1password

AGENTS

Development Rules (Checklist)

Workflow Notes

Design

Improvements / Backlog

Work Log

Dependencies

Review Questions

Documentation Language