# AGENTS.md

**Motto:** “Small, clear, safe steps — always grounded in real docs.”

---

## Principles

* Keep every change minimal, reversible, and easy to roll back.
* Favour clarity over cleverness; simplicity over complexity.
* Avoid introducing new dependencies unless absolutely necessary; prune unused ones whenever possible.
* Please help clarify the goals and deliverables of the task I am about to discuss. Let's start by clarifying the goals. Please proceed in a flow where you provide suggestions and check with me to ensure the direction is correct.

---

## Knowledge & Libraries

* When in doubt, pause and ask for clarification before proceeding.

---

## Workflow

### Slash Commands (LLM helpers)

The following chat slash commands are mapped to project scripts. When a user types these in Codex CLI or Claude Code, resolve them to shell execution of the corresponding script (arguments are forwarded):

- `/test …` → run `bin/test …` (delegates to `scripts/run_pytest.py`)
- `/test-failed …` → run `bin/test-failed …`
- `/test-changed [--range RANGE] …` → run `bin/test-changed …` (uses git diff; falls back to last-failed)

Environment is normalized by the runner; prefer these over raw `python -m pytest` to keep outputs consistent.

* **Plan:** Present a concise plan before any non-trivial work and keep it updated until completion.
* **Read:** Identify all relevant files and read them completely before editing.
* **Verify:** Check assumptions against the docs; after modifications, re-read the affected code to confirm syntax and formatting.
* **Implement:** Keep scope tight, aiming for modular, single-purpose changes.
* **Test & Docs:** For each change, add at least one test and update the relevant documentation so behaviour stays aligned with business logic.
* **Reflect:** Address root causes and consider adjacent risks to prevent regressions.
* ログレベルと出力方針の詳細は `docs/guides/logging_guidelines.md` を参照。

### Additional Slash Commands

- `/scan-encoding …` → run `bin/scan-encoding …`（U+FFFD を検出し、レポートを `reports/encoding_scan_findings.txt` に出力。warn-only）

### LLMタスクの Definition of Done（DoD）

- 計画提示: 目的・前提・制約・影響範囲を簡潔に共有（Plan を更新）。
- 最小差分: 既存の仕組み（`bin/test*`/`scripts/run_pytest.py` など）を尊重し、変更は最小限。
- テスト通過: `/test …`（または `/test-changed`/`/test-failed`）を実行し、グリーンであることを確認（ログ要提示）。
- 整合確認: 実装とドキュメントの差異を照合し、必要に応じてどちらか（または両方）を更新。
- 変更要約: 変更点・理由・影響を3行で要約（コミットメッセージ/レポートに転載可）。

### 禁止事項と安全運用（失敗パターン対策）

- 指示の“再解釈”による独自高速化を禁止（読み飛ばし・勝手な並列化・コマンド置換をしない）。
- コミット/デプロイ/破壊的 Git 操作（`reset --hard`, `checkout -f` 等）は、明示指示がある場合のみ。実行前にバックアップブランチ `backup/<YYYYMMDD-HHMM>` を作成。
- テスト/リンタ未通過の状態で「完了」宣言をしない（ログ提示とセットで報告）。
- 既存実装の確認なく重複実装しない。新規はまず既存の拡張を検討。
- 型安全を軽視しない。`Any` は最後の手段。型ガード/strict 設定を尊重（詳細はプロジェクトの型設定に従う）。

### 仕様整合チェック（Tools）

- コメント/ヘッダ整合: `python scripts/comment_header_audit.py --tiered`
- DDD/TDD 整合（変更影響に応じた検査レベル調整を含む）: `python scripts/check_tdd_ddd_compliance.py`
- テンプレ移行の情報欠落検査: `python scripts/audit_template_content_parity.py`
- 文字化け早期検知（warn-only）: `/scan-encoding`（= `bin/scan-encoding`）

### プロンプト運用（固定/変数）

- 固定プロンプト（振る舞い/スタイル/禁止事項）は本ドキュメント（AGENTS.md）の「Claude/MCP 契約」節に集約。
- 変数プロンプト（タスク固有の指示/制約/入出力/検証条件）は `prompts/task_template.md` をベースに作成し、都度差し込み。
- 作業は「1つの仮説 / 1つの変更」に限定。コミット粒度もこれに合わせる。

---

## Code Style & Limits

* Target ≤ 300 lines per file; keep modules focused on a single responsibility.
* Comments: open each file with a short header (where/what/why). Subsequent comments should explain **intent (Why)**, **purpose (What)**, or **higher-level design decisions**—avoid restating obvious code.
* Commenting habit: capture rationale, assumptions, and trade-offs so future readers understand the reasoning.
* Docstrings: write all module/class/function docstrings in English, using sections such as Args / Returns / Raises when they improve clarity.

補足（型安全）:

- `Any` の安易な使用を避け、必要時は根拠をコメントに明記。可能な限り型ガード/ナローイングを適用する。
- 可能であれば型チェッカ（例: mypy/pyright）の strict 設定を尊重し、逸脱は局所化する。

---

## Claude/MCP 契約（統合）

本節は旧 CLAUDE.md の内容を統合した「Claude Code + MCP 環境」向けの追加契約です。以後、SSOT は AGENTS.md とします。

### 言語と出力
- ユーザーへの返答は日本語（技術用語の英語は許容）。
- 既定は軽量出力（B20方針）。長文の全貼り付けを避け、`issue_id`/`file_hash`/`line_hash`/`block_hash` など安定参照子を優先。

### MCP オペレーション
- エントリポイント: MCP 関連は `noveler.presentation.mcp.*` を基点とする。
- サーバ設定の更新: `./bin/setup_mcp_configs` を用いて `codex.mcp.json` と `.mcp/config.json`（および Claude デスクトップ設定）を安全に更新。
- SSOT: `scripts/setup/update_mcp_configs.py::ensure_mcp_server_entry()` は開発/配布の双方に対応した設定生成の単一情報源。

### 実装規約（要点）
- import は `noveler.` プレフィクスを使用。相対/ワイルドカード import は禁止（一行一import）。
- 共有ユーティリティ（例: `noveler.presentation.cli.shared_utilities.console`）を利用し、`Console` の直接生成や `import logging` の直使用、ハードコードパスは禁止。
- 呼び出し経路は UseCase 層または MessageBus を経由（DDDの依存方向を順守）。
- 設定・パス参照は `get_config_manager()`/Path Service を使用。`os.getenv(...)` の直参照は禁止（アダプタ経由）。
- 命名規約: 関数/変数 `snake_case`、クラス `PascalCase`、定数 `SCREAMING_SNAKE_CASE`。

### テストと品質
- 新規機能は「仕様→テスト→実装→リファクタ」の順。各変更は最低1テストと対応ドキュメントを含む。
- 品質チェック統合口: `run_quality_checks`（必要に応じ `fix_quality_issues`・`improve_quality_until`）。
- 失敗ストリームは NDJSON を既定（CI で fail-only）。最小出力が必要な場合は `/bin/test-json` を利用。

### 変更ポリシー
- 以後、CLAUDE.md は廃止（スタブ化）。Claude/MCP 固有の契約は本節を更新する。
- 手順や背景説明は、必要に応じて参照ドキュメント（`docs/runbooks`、`CODEMAP.yaml` など）へ記載。

### Comment & Docstring Standards (Tiered Approach)

**Rationale**: Domain layer contains business logic (= specification); other layers are self-explanatory with type hints. A one-size-fits-all approach is impractical (50k violations); tiered standards balance quality with development velocity.

#### Header Comment (Required in All Layers)

Every Python module must open with an English header comment. Use the following template:

```
# File: <relative/path.py>
# Purpose: <summarise the module's responsibility and why it exists>
# Context: <note key dependencies, domain constraints, or consumers>
```

#### Tier 1: Domain Layer (STRICT) ⭐⭐⭐⭐⭐

**Path**: `src/noveler/domain/**`
**Rationale**: Business logic = specification foundation; docstrings form basis for automated specification generation

**Required docstring sections** for all classes/functions:
- **Purpose**: What and why (2-3 sentences)
- **Args**: All parameters (unless trivial from type hints)
- **Returns**: Return value meaning (required if function returns)
- **Raises**: Intentional exceptions (required if function raises)
- **Side Effects**: State changes, I/O, events (or explicit "None")

**Example - Good** ✅:
```python
def calculate_royalty(sales: Decimal, rate: Decimal) -> Decimal:
    """
    印税を計算する（消費税込み、最小単位1円）。

    Purpose:
        売上金額と印税率から著者への支払額を算出。
        端数は切り捨て（出版業界慣習）。

    Args:
        sales: 税込売上金額（負数不可）
        rate: 印税率（0.0-1.0の範囲）

    Returns:
        計算された印税額（円単位、Decimal型で精度保証）

    Raises:
        ValueError: salesが負数、またはrateが範囲外の場合

    Side Effects:
        None - 純粋関数
    """
```

---

#### Tier 2: Application Layer (MODERATE) ⭐⭐⭐

**Path**: `src/noveler/application/**`
**Rationale**: Use cases + type hints are often self-explanatory; detailed docstrings add little value

**Required docstring sections**:
- **Purpose**: 1-2 sentence summary (required)
- **Args/Returns/Raises**: Only if NOT obvious from type hints
- **Side Effects**: Only if non-trivial (e.g., DB writes, file I/O)

**Example - Good** ✅:
```python
def create_episode(
    title: str,
    manuscript: Manuscript
) -> Episode:
    """新規エピソードを作成し、永続化する。"""
    # Type hints make Args/Returns self-evident
```

---

#### Tier 3: Infrastructure Layer (RELAXED) ⭐⭐

**Path**: `src/noveler/infrastructure/**`
**Rationale**: Implementation IS the specification for I/O and persistence

**Required**:
- One-line docstring summary only
- Detailed docstring only for:
  - Complex error handling patterns
  - Non-obvious side effects (e.g., caching, retry logic)
  - Performance considerations

**Example - Good** ✅:
```python
def save_to_file(path: Path, data: str) -> None:
    """ファイルに保存"""
```

---

#### Tier 4: Presentation Layer (MINIMAL) ⭐

**Path**: `src/noveler/presentation/**`
**Rationale**: UI code changes frequently; detailed docs become stale

**Required**:
- One-line summary (optional for trivial functions)
- Header comment in file

**Example**:
```python
def render_episode_card(episode: Episode) -> str:
    """エピソードをHTML表示"""
```

---

#### Tier 5: Tests (EXEMPT)

**Path**: `tests/**`
**Rationale**: Test names should be self-documenting

**Example**:
```python
def test_create_episode_with_invalid_title_raises_validation_error():
    # No docstring needed - test name is specification
```

---

#### Enforcement

* **New/changed code**: Must comply with tier-specific standards (enforced by pre-commit hook)
* **Existing violations**: Recorded as technical debt; no forced migration (50,474 existing violations)
* **Baseline**: `reports/docstring_violations_baseline_2025_10_26.json`
* **Verification**: `python scripts/comment_header_audit.py --tiered`
* **Auto-generation**: `python scripts/generate_docstring_templates.py --tiered <file.py>`

---

* Keep comments concise and factual; favour intent and decision rationale over restating code.
* Configuration: centralise tunables in `config.py`; avoid hard-coded magic numbers in code and tests. Pull defaults from config when wiring dependencies.
* Simplicity: implement exactly what is requested—no unsolicited features.

---

## Collaboration & Accountability

* Escalate immediately when requirements are ambiguous, security-sensitive, or when UX/API contracts would change.
* Be transparent about confidence: if confidence falls below 80%, state it and request help. Honesty scores 0 points; incorrect changes cost –4; correct outcomes score +1.
* Optimise for correctness over speed—preventing a bad change is worth more than shipping quickly.

---

## Quick Checklist

Plan → Read → Verify → Implement → Test & Docs → Reflect

---

## LLM-Friendly Tests (pytest)

- 推奨: `make test` を使用すると、LLM向け要約が常に生成されます。
- レポート出力: `reports/llm_summary.{jsonl,txt}`。STDOUTには `LLM:BEGIN ... LLM:END` で囲まれた要約も出力。

Examples:
- フル実行（静かめ）: `make test`
- 詳細表示: `make test VV=1`
- 個別ノード: `make test FILE=tests/test_api.py::TestUser::test_create`
- `-k`式: `make test K='user and not slow'`
- マーカー: `make test M='unit'`
- 直pytestでも同等出力: `pytest -q --llm-report` または `LLM_REPORT=1 pytest -q`
- 直近失敗の再実行: `make test-last`
- 変更分のテスト（git差分）: `make test-changed` または `make test-changed RANGE=origin/main...HEAD`

Notes:
- 出力ディレクトリは `LLM_REPORT_DIR=out` で変更可能（make/pytestどちらでも）。
- 出力フォーマットは既定 `jsonl,txt`。`LLM_REPORT_FORMAT=txt` などで変更可能。
