0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

生成AIはマニュアルだけでプログラムを書けるのか?

0
Posted at

はじめに

ライブラリを利用してプログラムを開発するとき、私たちは何を参考にするでしょうか。
初めて利用するライブラリの場合、マニュアルを読んだだけでは使い方が分からず、サンプルコードを探すことも少なくありません。

では、生成AIの場合はどうでしょうか。

生成AIはマニュアルだけでプログラムを書けるのでしょうか。
それとも、サンプルコードがあった方が良いのでしょうか。

今回は検証用Pythonライブラリを作成し、生成AIに与える資料を変えながら、プログラムの生成結果を比較してみました。

検証の目的

今回の検証では、生成AIに与える資料を次の3パターンに分けます。

条件 提供する資料
A マニュアルのみ
B サンプルコードのみ
C マニュアル+サンプルコード

それぞれの条件で同じ開発依頼を5回ずつ実行し、生成されたプログラムを比較します。

今回確認したいのは、次の3点です。

  1. マニュアルだけで正しいプログラムを生成できるか
  2. サンプルコードだけでもプログラムを生成できるか
  3. マニュアルとサンプルコードを組み合わせることで精度が向上するか

なお、今回は生成AIの学習データに含まれている可能性がある既存ライブラリを避け、検証用の独自ライブラリを作成しています。

検証環境

生成AIのモデル

今回は、資料の違いによる生成結果の差を確認するため、Gemini 3.5 Flash-Liteを使用しました。

検証用ライブラリ

検証用にpipeledgerという管路の点検履歴を管理するPythonライブラリを用意しました。
機能は次の通りです。

機能 API 内容
接続 connect() データベース接続
切断 close() 接続終了
点検登録 register_inspection() 点検履歴登録
点検検索 query_inspections() 点検履歴検索
CSV出力 export_csv() 点検履歴出力

APIには、いくつかの制約を設けています。

  • 接続前にAPIを呼び出すことはできない
  • 点検日時にはタイムゾーン情報が必要
  • 点検状態は整数1~5
  • タグは最大5個
  • 同一管路番号・同一日時の重複登録は禁止
  • 検索開始日時は検索対象に含む
  • 検索終了日時は検索対象に含まない
  • CSV出力先の親ディレクトリは事前に存在する必要がある

マニュアル

以下が利用するライブラリのマニュアルです。

マニュアル
# PipeLedger API Reference

Version: 1.0.0

## 1. 概要

PipeLedgerは、下水道管路の点検履歴を管理するPythonライブラリです。
Python 3.10以上に対応しています。

## 2. クラス

### PipeLedger(storage_path)
点検履歴管理オブジェクトを生成します。

Parameters:
- storage_path: str
  - データ保存先ディレクトリ

Note:
- インスタンス生成時点では接続されません。
- APIを使用するにはconnect()が必要です。

## 3. 機能

### connect()

データストアに接続します。

Returns:
- None

Exceptions:
- ConnectionError:
  既に接続されている場合

### close()

接続を終了します。

Returns:
- None

Exceptions:
- ConnectionError:
  接続されていない場合

### register_inspection()

点検履歴を登録します。

Signature:
register_inspection(
    pipe_id: str,
    inspected_at: datetime,
    condition: int,
    note: str = "",
    tags: Iterable[str] = ()
) -> InspectionReceipt

Parameters:
- pipe_id:
  管路番号。空文字は禁止。

- inspected_at:
  点検日時。タイムゾーン情報が必須。

- condition:
  点検状態。整数1~5。

- note:
  備考。最大120文字。

- tags:
  タグのコレクション。最大5個。

Tag rules:
- 前後の空白を除去する。
- 小文字に変換する。
- 空文字は禁止。
- 重複は禁止。

Returns:

InspectionReceipt:
- inspection_id: int
- pipe_id: str

Exceptions:
- ConnectionError
- ValidationError
- DuplicateInspectionError

Duplicate rule:
同一pipe_idかつ同一inspected_atの登録は禁止。

### query_inspections()
点検履歴を検索します。

Signature:
query_inspections(
    pipe_id: str | None = None,
    since: datetime | None = None,
    until: datetime | None = None
) -> list[Inspection]

Parameters:
- pipe_id:
  管路番号。Noneの場合は全管路。
- since:
  検索開始日時。Noneの場合は制限なし。
- until:
  検索終了日時。Noneの場合は制限なし。

Search rules:
- sinceは検索対象に含む。
- untilは検索対象に含まない。
- 日時にはタイムゾーン情報が必要。
- sinceはuntilより前でなければならない。

Returns:
Inspectionのリスト。

Inspection fields:
- pipe_id
- inspected_at
- condition
- note
- tags

Sort order:
1. pipe_idの昇順
2. inspected_atの昇順

### export_csv()
点検履歴をCSV出力します。

Signature:
export_csv(
    destination: str,
    pipe_ids: Iterable[str] | None = None
) -> ExportResult

Parameters:
- destination:
  出力先ファイルパス。
- pipe_ids:
  出力対象の管路番号。
  Noneの場合は全件出力。

Output format:
- Encoding: UTF-8 with BOM
- Header:
  pipe_id, inspected_at, condition, note, tags
- Date format: ISO 8601
- Tags separator: |

Sort order:
1. pipe_idの昇順
2. inspected_atの昇順

Note:
出力先の親ディレクトリは事前に存在する必要があります。

Returns:

ExportResult:
- path: Path
- rows_written: int

Exceptions:
- ConnectionError
- ValidationError

## 4. 共通事項

以下のAPIは接続状態でのみ使用できます。

- register_inspection()
- query_inspections()
- export_csv()

close()後は再接続しない限り使用できません。

サンプルコード

以下が利用するライブラリのサンプルコードです。

サンプルコード
from datetime import datetime
from zoneinfo import ZoneInfo
from pipeledger import PipeLedger

def main():
    ledger = PipeLedger("./data")

    try:
        ledger.connect()

        receipt = ledger.register_inspection(
            pipe_id="P-001",
            inspected_at=datetime(
                2026, 10, 1, 10, 0,
                tzinfo=ZoneInfo("Asia/Tokyo")
            ),
            condition=3,
            note="通常点検",
            tags=["routine", "visual"]
        )

        print(
            f"Registered: {receipt.inspection_id}"
        )

        inspections = ledger.query_inspections(
            pipe_id="P-001",
            since=datetime(
                2026, 10, 1, 0, 0,
                tzinfo=ZoneInfo("Asia/Tokyo")
            ),
            until=datetime(
                2026, 11, 1, 0, 0,
                tzinfo=ZoneInfo("Asia/Tokyo")
            )
        )

        for item in inspections:
            print(
                item.pipe_id,
                item.inspected_at,
                item.condition
            )

        result = ledger.export_csv(
            "./data/inspections.csv",
            pipe_ids=["P-001"]
        )

        print(
            f"Exported: {result.rows_written}"
        )

    finally:
        ledger.close()

if __name__ == "__main__":
    main()

指示内容

開発依頼

以下が開発依頼の内容です。

開発依頼
# 開発依頼:管路点検履歴の登録・検索・出力

## 1. 概要

管路点検履歴を管理するPythonプログラムを作成してください。

指定された点検履歴を登録し、特定の管路の履歴を検索して、CSVファイルに出力します。

## 2. 要件

### 2.1 初期設定
- データ保存先は ./data とする。
- 必要なオブジェクトを生成する。
- 処理終了時には適切に接続を終了する。

### 2.2 点検履歴登録
以下の3件を登録する。

| 管路番号 | 点検日時 | 状態 | 備考 |
|---|---|---:|---|
| P-002 | 2026-10-01 10:00 | 3 | 定期点検 |
| P-001 | 2026-10-02 10:00 | 2 | 軽微な劣化 |
| P-001 | 2026-10-03 10:00 | 4 | 要経過観察 |

すべて日本時間として扱う。

タグは以下のとおり。
- P-002:routine
- P-001(10月2日):visual
- P-001(10月3日):followup

### 2.3 点検履歴検索
以下の条件で検索する。
- 管路番号:P-001
- 開始日時:2026-10-02 00:00
- 終了日時:2026-10-04 00:00

検索結果について、以下を表示する。
- 管路番号
- 点検日時
- 点検状態
- 備考

### 2.4 CSV出力
検索結果と同じ条件に該当する点検履歴をCSVファイルに出力する。

出力先:
./output/inspection.csv

出力対象:
P-001の点検履歴のみ。

出力結果の件数を画面に表示する。

## 3. 実装条件
- Python 3.10以上。
- PipeLedgerライブラリを利用する。
- 標準ライブラリ以外の追加パッケージは禁止。
- 例外発生時にも接続を適切に終了する。
- 出力先ディレクトリが存在しない場合は作成する。
- 処理内容が分かるように適切なコメントを記述する。

## 4. 成果物
main.py

プロンプト

あなたはPythonによるシステム開発を担当する熟練したソフトウェアエンジニアです。
提供されたライブラリの資料を確認し、開発依頼に従ってPythonプログラムを作成してください。

以下の点に注意してください。
1. 提供された資料を根拠として実装すること。
2. ライブラリのAPIを推測で作らないこと。
3. メソッドの引数、戻り値、呼び出し順序を確認すること。
4. ライブラリの制約事項を守ること。
5. 例外処理とリソースの解放を適切に行うこと。
6. Pythonの標準ライブラリを優先して使用すること。
7. 要件を満たす完全なコードを出力すること。

資料に記載されていない仕様がある場合は、勝手に仕様を作らず、その点を明示してください。
コードの説明は簡潔にし、最初に完成したコードを提示してください。

以下は利用するライブラリのマニュアルです。
```
[マニュアルの内容]
```

以下は利用するライブラリのサンプルコードです。
```
[サンプルコードの内容]
```

以下が開発依頼です。
```
[開発依頼の内容]
```

検証結果

マニュアルのみ
1回目
main.py
from datetime import datetime, timezone, timedelta
from pathlib import Path
from pipeledger import PipeLedger

def main():
    # 日本時間(JST = UTC+9)の定義
    jst = timezone(timedelta(hours=9))
    
    storage_path = "./data"
    output_dir = Path("./output")
    output_file = output_dir / "inspection.csv"
    
    # 出力先ディレクトリが存在しない場合は作成する
    output_dir.mkdir(parents=True, exist_ok=True)
    
    # PipeLedgerインスタンスの生成
    ledger = PipeLedger(storage_path)
    
    try:
        # データストアに接続
        ledger.connect()
        
        # 2.2 点検履歴登録
        # すべて日本時間として扱うため、タイムゾーン情報を付与する
        ledger.register_inspection(
            pipe_id="P-002",
            inspected_at=datetime(2026, 10, 1, 10, 0, tzinfo=jst),
            condition=3,
            note="定期点検",
            tags=["routine"]
        )
        
        ledger.register_inspection(
            pipe_id="P-001",
            inspected_at=datetime(2026, 10, 2, 10, 0, tzinfo=jst),
            condition=2,
            note="軽微な劣化",
            tags=["visual"]
        )
        
        ledger.register_inspection(
            pipe_id="P-001",
            inspected_at=datetime(2026, 10, 3, 10, 0, tzinfo=jst),
            condition=4,
            note="要経過観察",
            tags=["followup"]
        )
        
        # 2.3 点検履歴検索
        # 管路番号:P-001, 開始日時:2026-10-02 00:00 (JST), 終了日時:2026-10-04 00:00 (JST)
        since_dt = datetime(2026, 10, 2, 0, 0, tzinfo=jst)
        until_dt = datetime(2026, 10, 4, 0, 0, tzinfo=jst)
        
        search_results = ledger.query_inspections(
            pipe_id="P-001",
            since=since_dt,
            until=until_dt
        )
        
        print("--- 検索結果 ---")
        for inspection in search_results:
            print(f"管路番号: {inspection.pipe_id}, 点検日時: {inspection.inspected_at}, 状態: {inspection.condition}, 備考: {inspection.note}")
            
        # 2.4 CSV出力
        # P-001の点検履歴のみを指定して出力
        export_result = ledger.export_csv(
            destination=str(output_file),
            pipe_ids=["P-001"]
        )
        
        print(f"--- CSV出力完了 ---")
        print(f"出力件数: {export_result.rows_written} 件")
        print(f"保存先: {export_result.path}")

    except Exception as e:
        print(f"エラーが発生しました: {e}")
        raise
    finally:
        # 処理終了時には確実に接続を終了する
        try:
            ledger.close()
        except ConnectionError:
            pass

if __name__ == "__main__":
    main()
実行結果
--- 検索結果 ---
管路番号: P-001, 点検日時: 2026-10-02 10:00:00+09:00, 状態: 2, 備考: 軽微な劣化
管路番号: P-001, 点検日時: 2026-10-03 10:00:00+09:00, 状態: 4, 備考: 要経過観察
--- CSV出力完了 ---
出力件数: 2 件
保存先: output\inspection.csv
2回目
main.py
from datetime import datetime, timezone, timedelta
from pathlib import Path
from pipeledger import PipeLedger, ConnectionError, ValidationError, DuplicateInspectionError

def main():
    # 日本時間 (JST = UTC+9) のタイムゾーン定義
    jst = timezone(timedelta(hours=9))

    storage_path = "./data"
    output_dir = Path("./output")
    output_file = output_dir / "inspection.csv"

    # 出力先ディレクトリが存在しない場合は作成する
    output_dir.mkdir(parents=True, exist_ok=True)

    # 1. 初期設定: PipeLedger インスタンスの生成
    ledger = PipeLedger(storage_path)

    try:
        # データストアに接続
        ledger.connect()

        # 2. 点検履歴登録
        # すべて日本時間として扱うため、タイムゾーン情報を付与する
        inspections_to_register = [
            {
                "pipe_id": "P-002",
                "inspected_at": datetime(2026, 10, 1, 10, 0, tzinfo=jst),
                "condition": 3,
                "note": "定期点検",
                "tags": ["routine"]
            },
            {
                "pipe_id": "P-001",
                "inspected_at": datetime(2026, 10, 2, 10, 0, tzinfo=jst),
                "condition": 2,
                "note": "軽微な劣化",
                "tags": ["visual"]
            },
            {
                "pipe_id": "P-001",
                "inspected_at": datetime(2026, 10, 3, 10, 0, tzinfo=jst),
                "condition": 4,
                "note": "要経過観察",
                "tags": ["followup"]
            }
        ]

        for item in inspections_to_register:
            ledger.register_inspection(
                pipe_id=item["pipe_id"],
                inspected_at=item["inspected_at"],
                condition=item["condition"],
                note=item["note"],
                tags=item["tags"]
            )

        # 3. 点検履歴検索
        # 条件: 管路番号=P-001, 開始日時=2026-10-02 00:00 (JST), 終了日時=2026-10-04 00:00 (JST)
        search_pipe_id = "P-001"
        since_dt = datetime(2026, 10, 2, 0, 0, tzinfo=jst)
        until_dt = datetime(2026, 10, 4, 0, 0, tzinfo=jst)

        query_results = ledger.query_inspections(
            pipe_id=search_pipe_id,
            since=since_dt,
            until=until_dt
        )

        print("=== 検索結果 ===")
        for insp in query_results:
            print(f"管路番号: {insp.pipe_id}, 点検日時: {insp.inspected_at}, 状態: {insp.condition}, 備考: {insp.note}")

        # 4. CSV出力
        # 検索条件と同じ条件(P-001)に該当する点検履歴を出力する
        export_result = ledger.export_csv(
            destination=str(output_file),
            pipe_ids=[search_pipe_id]
        )

        print(f"\nCSV出力が完了しました。出力件数: {export_result.rows_written} 件")
        print(f"出力先: {export_result.path}")

    except (ConnectionError, ValidationError, DuplicateInspectionError) as e:
        print(f"エラーが発生しました: {e}", file=sys.stderr)
        raise
    finally:
        # 処理終了時には適切に接続を終了する(例外発生時も実行)
        try:
            ledger.close()
        except ConnectionError:
            # 既に接続されていない場合の例外は無視または許容
            pass

if __name__ == "__main__":
    import sys
    main()
実行結果
=== 検索結果 ===
管路番号: P-001, 点検日時: 2026-10-02 10:00:00+09:00, 状態: 2, 備考: 軽微な劣化
管路番号: P-001, 点検日時: 2026-10-03 10:00:00+09:00, 状態: 4, 備考: 要経過観察

CSV出力が完了しました。出力件数: 2 件
出力先: output\inspection.csv
3回目
main.py
from datetime import datetime, timedelta, timezone
from pathlib import Path
from pipeledger import PipeLedger


def main():
    # 日本時間 (JST: UTC+9) のタイムゾーン定義
    jst = timezone(timedelta(hours=9))

    storage_path = "./data"
    output_dir = Path("./output")
    output_csv_path = output_dir / "inspection.csv"

    # 出力先の親ディレクトリが存在しない場合は作成する
    output_dir.mkdir(parents=True, exist_ok=True)

    # PipeLedgerインスタンスの生成
    ledger = PipeLedger(storage_path)

    try:
        # データストアへ接続
        ledger.connect()

        # 2.2 点検履歴登録
        # すべて日本時間として扱うため、タイムゾーン情報を付与する
        inspections_to_register = [
            {
                "pipe_id": "P-002",
                "inspected_at": datetime(2026, 10, 1, 10, 0, tzinfo=jst),
                "condition": 3,
                "note": "定期点検",
                "tags": ["routine"],
            },
            {
                "pipe_id": "P-001",
                "inspected_at": datetime(2026, 10, 2, 10, 0, tzinfo=jst),
                "condition": 2,
                "note": "軽微な劣化",
                "tags": ["visual"],
            },
            {
                "pipe_id": "P-001",
                "inspected_at": datetime(2026, 10, 3, 10, 0, tzinfo=jst),
                "condition": 4,
                "note": "要経過観察",
                "tags": ["followup"],
            },
        ]

        for item in inspections_to_register:
            ledger.register_inspection(
                pipe_id=item["pipe_id"],
                inspected_at=item["inspected_at"],
                condition=item["condition"],
                note=item["note"],
                tags=item["tags"],
            )

        # 2.3 点検履歴検索
        # 管路番号: P-001, 開始日時: 2026-10-02 00:00 (JST), 終了日時: 2026-10-04 00:00 (JST)
        search_pipe_id = "P-001"
        search_since = datetime(2026, 10, 2, 0, 0, tzinfo=jst)
        search_until = datetime(2026, 10, 4, 0, 0, tzinfo=jst)

        query_results = ledger.query_inspections(
            pipe_id=search_pipe_id, since=search_since, until=search_until
        )

        print("--- 検索結果 ---")
        for inspection in query_results:
            print(
                f"管路番号: {inspection.pipe_id}, "
                f"点検日時: {inspection.inspected_at}, "
                f"点検状態: {inspection.condition}, "
                f"備考: {inspection.note}"
            )

        # 2.4 CSV出力
        # 出力対象: P-001の点検履歴のみ
        export_result = ledger.export_csv(
            destination=str(output_csv_path), pipe_ids=["P-001"]
        )

        print(f"\nCSV出力が完了しました。出力件数: {export_result.rows_written}件")

    except Exception as e:
        print(f"エラーが発生しました: {e}")
        raise
    finally:
        # 処理終了時には適切に接続を終了する(例外発生時も実行)
        try:
            ledger.close()
        except Exception:
            pass


if __name__ == "__main__":
    main()
実行結果
--- 検索結果 ---
管路番号: P-001, 点検日時: 2026-10-02 10:00:00+09:00, 点検状態: 2, 備考: 軽微な劣化
管路番号: P-001, 点検日時: 2026-10-03 10:00:00+09:00, 点検状態: 4, 備考: 要経過観察

CSV出力が完了しました。出力件数: 2件
4回目
main.py
from datetime import datetime, timezone, timedelta
from pathlib import Path
from pipeledger import PipeLedger

def main():
    # 日本時間 (JST: UTC+9) の定義
    JST = timezone(timedelta(hours=9))

    storage_path = "./data"
    output_dir = Path("./output")
    csv_destination = "./output/inspection.csv"

    # 出力先ディレクトリが存在しない場合は作成する
    output_dir.mkdir(parents=True, exist_ok=True)

    # PipeLedgerインスタンスの生成
    ledger = PipeLedger(storage_path)

    try:
        # 接続
        ledger.connect()

        # 2.2 点検履歴登録
        # すべて日本時間(JST)として扱い、タイムゾーン情報を付与する
        ledger.register_inspection(
            pipe_id="P-002",
            inspected_at=datetime(2026, 10, 1, 10, 0, tzinfo=JST),
            condition=3,
            note="定期点検",
            tags=["routine"]
        )

        ledger.register_inspection(
            pipe_id="P-001",
            inspected_at=datetime(2026, 10, 2, 10, 0, tzinfo=JST),
            condition=2,
            note="軽微な劣化",
            tags=["visual"]
        )

        ledger.register_inspection(
            pipe_id="P-001",
            inspected_at=datetime(2026, 10, 3, 10, 0, tzinfo=JST),
            condition=4,
            note="要経過観察",
            tags=["followup"]
        )

        # 2.3 点検履歴検索
        # 条件: 管路番号=P-001, 開始日時=2026-10-02 00:00 (JST), 終了日時=2026-10-04 00:00 (JST)
        since_dt = datetime(2026, 10, 2, 0, 0, tzinfo=JST)
        until_dt = datetime(2026, 10, 4, 0, 0, tzinfo=JST)

        inspections = ledger.query_inspections(
            pipe_id="P-001",
            since=since_dt,
            until=until_dt
        )

        print("=== 検索結果 ===")
        for insp in inspections:
            print(f"管路番号: {insp.pipe_id}, 点検日時: {insp.inspected_at}, 状態: {insp.condition}, 備考: {insp.note}")

        # 2.4 CSV出力
        # 出力対象: P-001の点検履歴のみ
        export_result = ledger.export_csv(
            destination=csv_destination,
            pipe_ids=["P-001"]
        )

        print(f"CSV出力完了: {export_result.path} (出力件数: {export_result.rows_written}件)")

    except Exception as e:
        print(f"エラーが発生しました: {e}", file=sys.stderr)
        raise
    finally:
        # 処理終了時には適切に接続を終了する(例外発生時も確実に実行)
        try:
            ledger.close()
        except ConnectionError:
            # 接続されていない状態でcloseが呼ばれた場合などの例外対策
            pass

if __name__ == "__main__":
    import sys
    main()
実行結果
=== 検索結果 ===
管路番号: P-001, 点検日時: 2026-10-02 10:00:00+09:00, 状態: 2, 備考: 軽微な劣化
管路番号: P-001, 点検日時: 2026-10-03 10:00:00+09:00, 状態: 4, 備考: 要経過観察
CSV出力完了: output\inspection.csv (出力件数: 2件)
5回目
main.py
from datetime import datetime, timezone, timedelta
from pathlib import Path
from pipeledger import PipeLedger

def main():
    # 日本時間 (JST: UTC+9) の定義
    JST = timezone(timedelta(hours=9))
    
    storage_path = "./data"
    output_dir = Path("./output")
    csv_destination = output_dir / "inspection.csv"
    
    # 出力先ディレクトリが存在しない場合は作成する
    output_dir.mkdir(parents=True, exist_ok=True)
    
    # PipeLedgerインスタンスの生成
    ledger = PipeLedger(storage_path)
    
    try:
        # データストアに接続
        ledger.connect()
        
        # 2.2 点検履歴登録
        # すべて日本時間 (JST) として扱うため、タイムゾーン情報を付与する
        inspections_to_register = [
            {
                "pipe_id": "P-002",
                "inspected_at": datetime(2026, 10, 1, 10, 0, tzinfo=JST),
                "condition": 3,
                "note": "定期点検",
                "tags": ["routine"]
            },
            {
                "pipe_id": "P-001",
                "inspected_at": datetime(2026, 10, 2, 10, 0, tzinfo=JST),
                "condition": 2,
                "note": "軽微な劣化",
                "tags": ["visual"]
            },
            {
                "pipe_id": "P-001",
                "inspected_at": datetime(2026, 10, 3, 10, 0, tzinfo=JST),
                "condition": 4,
                "note": "要経過観察",
                "tags": ["followup"]
            }
        ]
        
        for item in inspections_to_register:
            try:
                ledger.register_inspection(
                    pipe_id=item["pipe_id"],
                    inspected_at=item["inspected_at"],
                    condition=item["condition"],
                    note=item["note"],
                    tags=item["tags"]
                )
            except Exception as e:
                # 既に登録されている場合などの例外を想定(必要に応じてハンドリング)
                pass

        # 2.3 点検履歴検索
        # 条件:管路番号 P-001、開始 2026-10-02 00:00 (JST)、終了 2026-10-04 00:00 (JST)
        since_time = datetime(2026, 10, 2, 0, 0, tzinfo=JST)
        until_time = datetime(2026, 10, 4, 0, 0, tzinfo=JST)
        
        search_results = ledger.query_inspections(
            pipe_id="P-001",
            since=since_time,
            until=until_time
        )
        
        print("=== 検索結果 ===")
        for insp in search_results:
            print(f"管路番号: {insp.pipe_id}, 点検日時: {insp.inspected_at}, 状態: {insp.condition}, 備考: {insp.note}")
            
        # 2.4 CSV出力
        # 出力先の親ディレクトリは事前に存在する必要があるため、上述のmkdirで対応済み
        # pipe_idsには出力対象の管路番号リストを指定
        export_result = ledger.export_csv(
            destination=str(csv_destination),
            pipe_ids=["P-001"]
        )
        
        print(f"\nCSV出力完了: {export_result.path} (出力件数: {export_result.rows_written}件)")

    except Exception as e:
        print(f"エラーが発生しました: {e}")
        raise
    finally:
        # 処理終了時には適切に接続を終了する(例外発生時も確実に実行)
        try:
            ledger.close()
        except Exception:
            pass

if __name__ == "__main__":
    main()
実行結果
=== 検索結果 ===
管路番号: P-001, 点検日時: 2026-10-02 10:00:00+09:00, 状態: 2, 備考: 軽微な劣化
管路番号: P-001, 点検日時: 2026-10-03 10:00:00+09:00, 状態: 4, 備考: 要経過観察

CSV出力完了: output\inspection.csv (出力件数: 2件)
サンプルコードのみ
1回目
main.py
from datetime import datetime
from zoneinfo import ZoneInfo
from pathlib import Path
from pipeledger import PipeLedger

def main():
    # 1. 初期設定:データ保存先は "./data"
    data_dir = "./data"
    output_path = Path("./output/inspection.csv")
    
    # 出力先ディレクトリが存在しない場合は作成する
    output_path.parent.mkdir(parents=True, exist_ok=True)

    ledger = PipeLedger(data_dir)

    try:
        # 接続の開始
        ledger.connect()

        # 2. 点検履歴登録(指定された3件)
        # 1件目: P-002
        ledger.register_inspection(
            pipe_id="P-002",
            inspected_at=datetime(
                2026, 10, 1, 10, 0,
                tzinfo=ZoneInfo("Asia/Tokyo")
            ),
            condition=3,
            note="定期点検",
            tags=["routine"]
        )

        # 2件目: P-001 (10月2日)
        ledger.register_inspection(
            pipe_id="P-001",
            inspected_at=datetime(
                2026, 10, 2, 10, 0,
                tzinfo=ZoneInfo("Asia/Tokyo")
            ),
            condition=2,
            note="軽微な劣化",
            tags=["visual"]
        )

        # 3件目: P-001 (10月3日)
        ledger.register_inspection(
            pipe_id="P-001",
            inspected_at=datetime(
                2026, 10, 3, 10, 0,
                tzinfo=ZoneInfo("Asia/Tokyo")
            ),
            condition=4,
            note="要経過観察",
            tags=["followup"]
        )

        # 3. 点検履歴検索
        # 管路番号:P-001, 開始日時:2026-10-02 00:00, 終了日時:2026-10-04 00:00
        inspections = ledger.query_inspections(
            pipe_id="P-001",
            since=datetime(
                2026, 10, 2, 0, 0,
                tzinfo=ZoneInfo("Asia/Tokyo")
            ),
            until=datetime(
                2026, 10, 4, 0, 0,
                tzinfo=ZoneInfo("Asia/Tokyo")
            )
        )

        # 検索結果の表示(管路番号、点検日時、点検状態、備考)
        # ※資料のサンプルコードから属性名(pipe_id, inspected_at, condition, note)を参照
        for item in inspections:
            print(
                f"管路番号: {item.pipe_id}, "
                f"点検日時: {item.inspected_at}, "
                f"点検状態: {item.condition}, "
                f"備考: {getattr(item, 'note', '')}"
            )

        # 4. CSV出力
        # 出力先:./output/inspection.csv, 出力対象:P-001の点検履歴のみ
        result = ledger.export_csv(
            str(output_path),
            pipe_ids=["P-001"]
        )

        # 出力結果の件数を画面に表示する
        print(f"Exported: {result.rows_written}")

    finally:
        # 例外発生時にも確実に接続を終了する
        ledger.close()

if __name__ == "__main__":
    main()
実行結果
管路番号: P-001, 点検日時: 2026-10-02 10:00:00+09:00, 点検状態: 2, 備考: 軽微な劣化
管路番号: P-001, 点検日時: 2026-10-03 10:00:00+09:00, 点検状態: 4, 備考: 要経過観察
Exported: 2
2回目
main.py
from datetime import datetime
from zoneinfo import ZoneInfo
from pathlib import Path
from pipeledger import PipeLedger

def main():
    # データ保存先の設定
    ledger = PipeLedger("./data")

    try:
        # 接続の開始
        ledger.connect()

        # 2.2 点検履歴の登録(3件)
        ledger.register_inspection(
            pipe_id="P-002",
            inspected_at=datetime(2026, 10, 1, 10, 0, tzinfo=ZoneInfo("Asia/Tokyo")),
            condition=3,
            note="定期点検",
            tags=["routine"]
        )

        ledger.register_inspection(
            pipe_id="P-001",
            inspected_at=datetime(2026, 10, 2, 10, 0, tzinfo=ZoneInfo("Asia/Tokyo")),
            condition=2,
            note="軽微な劣化",
            tags=["visual"]
        )

        ledger.register_inspection(
            pipe_id="P-001",
            inspected_at=datetime(2026, 10, 3, 10, 0, tzinfo=ZoneInfo("Asia/Tokyo")),
            condition=4,
            note="要経過観察",
            tags=["followup"]
        )

        # 2.3 点検履歴の検索
        inspections = ledger.query_inspections(
            pipe_id="P-001",
            since=datetime(2026, 10, 2, 0, 0, tzinfo=ZoneInfo("Asia/Tokyo")),
            until=datetime(2026, 10, 4, 0, 0, tzinfo=ZoneInfo("Asia/Tokyo"))
        )

        print("--- 検索結果 ---")
        for item in inspections:
            # ※注記: 検索結果オブジェクトの備考プロンプト(note)について、
            # 提供されたサンプルコード内には記載がないため、存在を仮定してアクセスしています。
            note = getattr(item, "note", "N/A")
            print(
                f"管路番号: {item.pipe_id}, "
                f"点検日時: {item.inspected_at}, "
                f"点検状態: {item.condition}, "
                f"備考: {note}"
            )

        # 2.4 CSV出力(出力先ディレクトリが存在しない場合は作成)
        output_dir = Path("./output")
        output_dir.mkdir(parents=True, exist_ok=True)
        output_file = output_dir / "inspection.csv"

        result = ledger.export_csv(
            str(output_file),
            pipe_ids=["P-001"]
        )

        print(f"Exported: {result.rows_written} 件")

    finally:
        # 処理終了時の確実な接続終了
        ledger.close()

if __name__ == "__main__":
    main()
実行結果
--- 検索結果 ---
管路番号: P-001, 点検日時: 2026-10-02 10:00:00+09:00, 点検状態: 2, 備考: 軽微な劣化
管路番号: P-001, 点検日時: 2026-10-03 10:00:00+09:00, 点検状態: 4, 備考: 要経過観察
Exported: 2 件
3回目
main.py
from datetime import datetime
from zoneinfo import ZoneInfo
from pathlib import Path
from pipeledger import PipeLedger

def main():
    # データ保存先の設定
    data_dir = "./data"
    output_dir = Path("./output")
    
    # 出力先ディレクトリが存在しない場合は作成する
    output_dir.mkdir(parents=True, exist_ok=True)
    csv_path = str(output_dir / "inspection.csv")

    # PipeLedgerのインスタンスを生成
    ledger = PipeLedger(data_dir)

    try:
        # 接続を開始
        ledger.connect()

        # 1. 点検履歴の登録 (3件)
        # P-002: 定期点検
        ledger.register_inspection(
            pipe_id="P-002",
            inspected_at=datetime(2026, 10, 1, 10, 0, tzinfo=ZoneInfo("Asia/Tokyo")),
            condition=3,
            note="定期点検",
            tags=["routine"]
        )

        # P-001 (10月2日): 軽微な劣化
        ledger.register_inspection(
            pipe_id="P-001",
            inspected_at=datetime(2026, 10, 2, 10, 0, tzinfo=ZoneInfo("Asia/Tokyo")),
            condition=2,
            note="軽微な劣化",
            tags=["visual"]
        )

        # P-001 (10月3日): 要経過観察
        ledger.register_inspection(
            pipe_id="P-001",
            inspected_at=datetime(2026, 10, 3, 10, 0, tzinfo=ZoneInfo("Asia/Tokyo")),
            condition=4,
            note="要経過観察",
            tags=["followup"]
        )

        # 2. 点検履歴の検索 (管路番号: P-001, 期間: 2026-10-02 00:00 ~ 2026-10-04 00:00)
        inspections = ledger.query_inspections(
            pipe_id="P-001",
            since=datetime(2026, 10, 2, 0, 0, tzinfo=ZoneInfo("Asia/Tokyo")),
            until=datetime(2026, 10, 4, 0, 0, tzinfo=ZoneInfo("Asia/Tokyo"))
        )

        # 検索結果の表示(管路番号、点検日時、点検状態、備考)
        print("--- 検索結果 ---")
        for item in inspections:
            print(
                f"管路番号: {item.pipe_id}, "
                f"点検日時: {item.inspected_at}, "
                f"点検状態: {item.condition}, "
                f"備考: {item.note}"
            )

        # 3. CSV出力 (P-001の点検履歴を ./output/inspection.csv に出力)
        result = ledger.export_csv(
            csv_path,
            pipe_ids=["P-001"]
        )

        # 出力結果の件数を画面に表示
        print(f"Exported: {result.rows_written}")

    finally:
        # 例外発生時にも確実に接続を終了する
        ledger.close()

if __name__ == "__main__":
    main()
実行結果
--- 検索結果 ---
管路番号: P-001, 点検日時: 2026-10-02 10:00:00+09:00, 点検状態: 2, 備考: 軽微な劣化
管路番号: P-001, 点検日時: 2026-10-03 10:00:00+09:00, 点検状態: 4, 備考: 要経過観察
Exported: 2
4回目
main.py
import os
from datetime import datetime
from zoneinfo import ZoneInfo
from pipeledger import PipeLedger

def main():
    # データ保存先の設定
    ledger = PipeLedger("./data")

    try:
        # 接続の開始
        ledger.connect()

        # 2.2 点検履歴の登録
        # 1件目 (P-002)
        ledger.register_inspection(
            pipe_id="P-002",
            inspected_at=datetime(2026, 10, 1, 10, 0, tzinfo=ZoneInfo("Asia/Tokyo")),
            condition=3,
            note="定期点検",
            tags=["routine"]
        )

        # 2件目 (P-001)
        ledger.register_inspection(
            pipe_id="P-001",
            inspected_at=datetime(2026, 10, 2, 10, 0, tzinfo=ZoneInfo("Asia/Tokyo")),
            condition=2,
            note="軽微な劣化",
            tags=["visual"]
        )

        # 3件目 (P-001)
        ledger.register_inspection(
            pipe_id="P-001",
            inspected_at=datetime(2026, 10, 3, 10, 0, tzinfo=ZoneInfo("Asia/Tokyo")),
            condition=4,
            note="要経過観察",
            tags=["followup"]
        )

        # 2.3 点検履歴の検索
        inspections = ledger.query_inspections(
            pipe_id="P-001",
            since=datetime(2026, 10, 2, 0, 0, tzinfo=ZoneInfo("Asia/Tokyo")),
            until=datetime(2026, 10, 4, 0, 0, tzinfo=ZoneInfo("Asia/Tokyo"))
        )

        # 検索結果の表示
        for item in inspections:
            print(
                item.pipe_id,
                item.inspected_at,
                item.condition,
                getattr(item, "note", "")
            )

        # 2.4 CSV出力
        output_dir = "./output"
        os.makedirs(output_dir, exist_ok=True)

        result = ledger.export_csv(
            os.path.join(output_dir, "inspection.csv"),
            pipe_ids=["P-001"]
        )

        print(f"Exported: {result.rows_written}")

    finally:
        # 例外発生時も含めて適切に接続を終了
        ledger.close()

if __name__ == "__main__":
    main()
実行結果
P-001 2026-10-02 10:00:00+09:00 2 軽微な劣化
P-001 2026-10-03 10:00:00+09:00 4 要経過観察
Exported: 2
5回目
main.py
import os
from datetime import datetime
from zoneinfo import ZoneInfo
from pipeledger import PipeLedger

def main():
    # 出力先ディレクトリが存在しない場合は作成する
    output_dir = "./output"
    os.makedirs(output_dir, exist_ok=True)

    # データ保存先を指定してオブジェクトを生成
    ledger = PipeLedger("./data")

    try:
        # 接続開始
        ledger.connect()

        # 2.2 点検履歴登録(3件)
        inspections_to_register = [
            {
                "pipe_id": "P-002",
                "inspected_at": datetime(2026, 10, 1, 10, 0, tzinfo=ZoneInfo("Asia/Tokyo")),
                "condition": 3,
                "note": "定期点検",
                "tags": ["routine"]
            },
            {
                "pipe_id": "P-001",
                "inspected_at": datetime(2026, 10, 2, 10, 0, tzinfo=ZoneInfo("Asia/Tokyo")),
                "condition": 2,
                "note": "軽微な劣化",
                "tags": ["visual"]
            },
            {
                "pipe_id": "P-001",
                "inspected_at": datetime(2026, 10, 3, 10, 0, tzinfo=ZoneInfo("Asia/Tokyo")),
                "condition": 4,
                "note": "要経過観察",
                "tags": ["followup"]
            }
        ]

        for insp in inspections_to_register:
            ledger.register_inspection(**insp)

        # 2.3 点検履歴検索
        inspections = ledger.query_inspections(
            pipe_id="P-001",
            since=datetime(2026, 10, 2, 0, 0, tzinfo=ZoneInfo("Asia/Tokyo")),
            until=datetime(2026, 10, 4, 0, 0, tzinfo=ZoneInfo("Asia/Tokyo"))
        )

        # 検索結果の表示
        for item in inspections:
            note = getattr(item, "note", "")
            print(
                f"管路番号: {item.pipe_id}, "
                f"点検日時: {item.inspected_at}, "
                f"点検状態: {item.condition}, "
                f"備考: {note}"
            )

        # 2.4 CSV出力
        result = ledger.export_csv(
            "./output/inspection.csv",
            pipe_ids=["P-001"]
        )

        # 出力結果の件数を画面に表示
        print(f"Exported: {result.rows_written}")

    finally:
        # 例外発生時も含めて確実に接続を終了
        ledger.close()

if __name__ == "__main__":
    main()
実行結果
管路番号: P-001, 点検日時: 2026-10-02 10:00:00+09:00, 点検状態: 2, 備考: 軽微な劣化
管路番号: P-001, 点検日時: 2026-10-03 10:00:00+09:00, 点検状態: 4, 備考: 要経過観察
Exported: 2
マニュアル+サンプル
1回目
main.py
from datetime import datetime
from pathlib import Path
from zoneinfo import ZoneInfo
from pipeledger import PipeLedger

def main():
    # 1. 初期設定
    storage_path = "./data"
    output_dir = Path("./output")
    
    # 出力先の親ディレクトリが存在しない場合は作成する
    output_dir.mkdir(parents=True, exist_ok=True)
    
    ledger = PipeLedger(storage_path)
    jst = ZoneInfo("Asia/Tokyo")

    try:
        # データストアに接続
        ledger.connect()

        # 2. 点検履歴登録
        # 2.1 P-002 (2026-10-01 10:00)
        ledger.register_inspection(
            pipe_id="P-002",
            inspected_at=datetime(2026, 10, 1, 10, 0, tzinfo=jst),
            condition=3,
            note="定期点検",
            tags=["routine"]
        )

        # 2.2 P-001 (2026-10-02 10:00)
        ledger.register_inspection(
            pipe_id="P-001",
            inspected_at=datetime(2026, 10, 2, 10, 0, tzinfo=jst),
            condition=2,
            note="軽微な劣化",
            tags=["visual"]
        )

        # 2.3 P-001 (2026-10-03 10:00)
        ledger.register_inspection(
            pipe_id="P-001",
            inspected_at=datetime(2026, 10, 3, 10, 0, tzinfo=jst),
            condition=4,
            note="要経過観察",
            tags=["followup"]
        )

        # 3. 点検履歴検索
        # 管路番号: P-001, 開始日時: 2026-10-02 00:00 (JST), 終了日時: 2026-10-04 00:00 (JST)
        since_time = datetime(2026, 10, 2, 0, 0, tzinfo=jst)
        until_time = datetime(2026, 10, 4, 0, 0, tzinfo=jst)

        inspections = ledger.query_inspections(
            pipe_id="P-001",
            since=since_time,
            until=until_time
        )

        print("--- 検索結果 ---")
        for item in inspections:
            print(
                f"管路番号: {item.pipe_id}, "
                f"点検日時: {item.inspected_at}, "
                f"点検状態: {item.condition}, "
                f"備考: {item.note}"
            )

        # 4. CSV出力
        # 出力先: ./output/inspection.csv, 対象: P-001の点検履歴
        csv_destination = "./output/inspection.csv"
        export_result = ledger.export_csv(
            destination=csv_destination,
            pipe_ids=["P-001"]
        )

        print(f"Exported rows: {export_result.rows_written}")

    except Exception as e:
        print(f"エラーが発生しました: {e}", file=sys.stderr)
        raise
    finally:
        # 処理終了時には適切に接続を終了する
        ledger.close()

if __name__ == "__main__":
    import sys
    main()
実行結果
--- 検索結果 ---
管路番号: P-001, 点検日時: 2026-10-02 10:00:00+09:00, 点検状態: 2, 備考: 軽微な劣化
管路番号: P-001, 点検日時: 2026-10-03 10:00:00+09:00, 点検状態: 4, 備考: 要経過観察
Exported rows: 2
2回目
main.py
from datetime import datetime
from pathlib import Path
from zoneinfo import ZoneInfo
from pipeledger import PipeLedger

def main():
    # データ保存先および出力先ディレクトリの設定
    storage_path = "./data"
    output_dir = Path("./output")
    output_csv_path = output_dir / "inspection.csv"

    # 出力先の親ディレクトリが存在しない場合は作成する
    output_dir.mkdir(parents=True, exist_ok=True)

    # PipeLedgerインスタンスの生成
    ledger = PipeLedger(storage_path)

    try:
        # データストアに接続
        ledger.connect()

        # 1. 点検履歴の登録(日本時間で指定)
        tz = ZoneInfo("Asia/Tokyo")

        # 登録1件目
        ledger.register_inspection(
            pipe_id="P-002",
            inspected_at=datetime(2026, 10, 1, 10, 0, tzinfo=tz),
            condition=3,
            note="定期点検",
            tags=["routine"]
        )

        # 登録2件目
        ledger.register_inspection(
            pipe_id="P-001",
            inspected_at=datetime(2026, 10, 2, 10, 0, tzinfo=tz),
            condition=2,
            note="軽微な劣化",
            tags=["visual"]
        )

        # 登録3件目
        ledger.register_inspection(
            pipe_id="P-001",
            inspected_at=datetime(2026, 10, 3, 10, 0, tzinfo=tz),
            condition=4,
            note="要経過観察",
            tags=["followup"]
        )

        # 2. 点検履歴の検索
        # 条件:管路番号 "P-001"、開始日時 2026-10-02 00:00、終了日時 2026-10-04 00:00
        inspections = ledger.query_inspections(
            pipe_id="P-001",
            since=datetime(2026, 10, 2, 0, 0, tzinfo=tz),
            until=datetime(2026, 10, 4, 0, 0, tzinfo=tz)
        )

        # 検索結果の表示
        print("--- 検索結果 ---")
        for item in inspections:
            print(
                f"管路番号: {item.pipe_id} | "
                f"点検日時: {item.inspected_at} | "
                f"点検状態: {item.condition} | "
                f"備考: {item.note}"
            )

        # 3. CSV出力
        # 出力先:./output/inspection.csv、出力対象:P-001の点検履歴
        result = ledger.export_csv(
            destination=str(output_csv_path),
            pipe_ids=["P-001"]
        )

        # 出力結果の件数を表示
        print(f"Exported: {result.rows_written} rows written to {result.path}")

    finally:
        # 例外発生時も含めて適切に接続を終了する
        ledger.close()

if __name__ == "__main__":
    main()
実行結果
--- 検索結果 ---
管路番号: P-001 | 点検日時: 2026-10-02 10:00:00+09:00 | 点検状態: 2 | 備考: 軽微な劣化
管路番号: P-001 | 点検日時: 2026-10-03 10:00:00+09:00 | 点検状態: 4 | 備考: 要経過観察
Exported: 2 rows written to output\inspection.csv
3回目
main.py
from datetime import datetime
from pathlib import Path
from zoneinfo import ZoneInfo
from pipeledger import PipeLedger

def main() -> None:
    # 1. 初期設定
    storage_path = "./data"
    output_dir = Path("./output")
    output_file = output_dir / "inspection.csv"

    # 出力先の親ディレクトリが存在しない場合は作成する
    output_dir.mkdir(parents=True, exist_ok=True)

    # PipeLedgerオブジェクトの生成
    ledger = PipeLedger(storage_path)

    try:
        # データストアへの接続
        ledger.connect()

        # 2. 点検履歴登録
        # 日本時間のタイムゾーン定義
        jst = ZoneInfo("Asia/Tokyo")

        # 1件目: P-002 (2026-10-01 10:00)
        ledger.register_inspection(
            pipe_id="P-002",
            inspected_at=datetime(2026, 10, 1, 10, 0, tzinfo=jst),
            condition=3,
            note="定期点検",
            tags=["routine"]
        )

        # 2件目: P-001 (2026-10-02 10:00)
        ledger.register_inspection(
            pipe_id="P-001",
            inspected_at=datetime(2026, 10, 2, 10, 0, tzinfo=jst),
            condition=2,
            note="軽微な劣化",
            tags=["visual"]
        )

        # 3件目: P-001 (2026-10-03 10:00)
        ledger.register_inspection(
            pipe_id="P-001",
            inspected_at=datetime(2026, 10, 3, 10, 0, tzinfo=jst),
            condition=4,
            note="要経過観察",
            tags=["followup"]
        )

        # 3. 点検履歴検索
        # 管路番号: P-001, 期間: 2026-10-02 00:00 ~ 2026-10-04 00:00 (JST)
        since_time = datetime(2026, 10, 2, 0, 0, tzinfo=jst)
        until_time = datetime(2026, 10, 4, 0, 0, tzinfo=jst)

        inspections = ledger.query_inspections(
            pipe_id="P-001",
            since=since_time,
            until=until_time
        )

        print("--- 検索結果 ---")
        for item in inspections:
            print(
                f"管路番号: {item.pipe_id}, "
                f"点検日時: {item.inspected_at}, "
                f"点検状態: {item.condition}, "
                f"備考: {item.note}"
            )

        # 4. CSV出力
        # P-001の点検履歴を対象に指定のファイルパスへ出力
        export_result = ledger.export_csv(
            destination=str(output_file),
            pipe_ids=["P-001"]
        )

        print(f"CSV出力完了: {export_result.path} (出力件数: {export_result.rows_written}件)")

    except Exception as e:
        print(f"エラーが発生しました: {e}", file=sys.stderr)
        raise
    finally:
        # 例外発生時も含め、処理終了時には必ず接続を終了する
        ledger.close()

if __name__ == "__main__":
    import sys
    main()
実行結果
--- 検索結果 ---
管路番号: P-001, 点検日時: 2026-10-02 10:00:00+09:00, 点検状態: 2, 備考: 軽微な劣化
管路番号: P-001, 点検日時: 2026-10-03 10:00:00+09:00, 点検状態: 4, 備考: 要経過観察
CSV出力完了: output\inspection.csv (出力件数: 2件)
4回目
main.py
from datetime import datetime
from pathlib import Path
from zoneinfo import ZoneInfo
from pipeledger import PipeLedger

def main():
    # 1. 初期設定
    storage_path = "./data"
    output_dir = Path("./output")
    
    # 出力先の親ディレクトリが存在しない場合は作成する
    output_dir.mkdir(parents=True, exist_ok=True)
    
    ledger = PipeLedger(storage_path)
    tokyo_tz = ZoneInfo("Asia/Tokyo")

    try:
        # データストアへ接続
        ledger.connect()

        # 2. 点検履歴登録(3件)
        # 1件目: P-002
        ledger.register_inspection(
            pipe_id="P-002",
            inspected_at=datetime(2026, 10, 1, 10, 0, tzinfo=tokyo_tz),
            condition=3,
            note="定期点検",
            tags=["routine"]
        )

        # 2件目: P-001 (10月2日)
        ledger.register_inspection(
            pipe_id="P-001",
            inspected_at=datetime(2026, 10, 2, 10, 0, tzinfo=tokyo_tz),
            condition=2,
            note="軽微な劣化",
            tags=["visual"]
        )

        # 3件目: P-001 (10月3日)
        ledger.register_inspection(
            pipe_id="P-001",
            inspected_at=datetime(2026, 10, 3, 10, 0, tzinfo=tokyo_tz),
            condition=4,
            note="要経過観察",
            tags=["followup"]
        )

        # 3. 点検履歴検索
        # 管路番号: P-001, 開始日時: 2026-10-02 00:00 (含める), 終了日時: 2026-10-04 00:00 (含めない)
        since_time = datetime(2026, 10, 2, 0, 0, tzinfo=tokyo_tz)
        until_time = datetime(2026, 10, 4, 0, 0, tzinfo=tokyo_tz)

        inspections = ledger.query_inspections(
            pipe_id="P-001",
            since=since_time,
            until=until_time
        )

        print("--- 検索結果 ---")
        for item in inspections:
            print(f"管路番号: {item.pipe_id}, 点検日時: {item.inspected_at}, 状態: {item.condition}, 備考: {item.note}")

        # 4. CSV出力
        # P-001の点検履歴を指定のファイルパスに出力
        csv_destination = "./output/inspection.csv"
        result = ledger.export_csv(
            destination=csv_destination,
            pipe_ids=["P-001"]
        )

        print(f"Exported: {result.rows_written} rows written to {result.path}")

    except Exception as e:
        print(f"エラーが発生しました: {e}")
        raise
    finally:
        # 処理終了時には確実に接続を終了する
        ledger.close()

if __name__ == "__main__":
    main()
実行結果
--- 検索結果 ---
管路番号: P-001, 点検日時: 2026-10-02 10:00:00+09:00, 状態: 2, 備考: 軽微な劣化
管路番号: P-001, 点検日時: 2026-10-03 10:00:00+09:00, 状態: 4, 備考: 要経過観察
Exported: 2 rows written to output\inspection.csv
5回目
main.py
from datetime import datetime
from pathlib import Path
from zoneinfo import ZoneInfo
from pipeledger import PipeLedger


def main():
    # 1. 初期設定
    storage_path = "./data"
    output_dir = Path("./output")
    output_csv_path = output_dir / "inspection.csv"

    # 出力先ディレクトリが存在しない場合は作成する
    output_dir.mkdir(parents=True, exist_ok=True)

    ledger = PipeLedger(storage_path)
    jst = ZoneInfo("Asia/Tokyo")

    try:
        # データストアに接続
        ledger.connect()

        # 2. 点検履歴の登録
        # 2.1 P-002の定期点検
        ledger.register_inspection(
            pipe_id="P-002",
            inspected_at=datetime(2026, 10, 1, 10, 0, tzinfo=jst),
            condition=3,
            note="定期点検",
            tags=["routine"],
        )

        # 2.2 P-001の軽微な劣化(10月2日)
        ledger.register_inspection(
            pipe_id="P-001",
            inspected_at=datetime(2026, 10, 2, 10, 0, tzinfo=jst),
            condition=2,
            note="軽微な劣化",
            tags=["visual"],
        )

        # 2.3 P-001の要経過観察(10月3日)
        ledger.register_inspection(
            pipe_id="P-001",
            inspected_at=datetime(2026, 10, 3, 10, 0, tzinfo=jst),
            condition=4,
            note="要経過観察",
            tags=["followup"],
        )

        # 3. 点検履歴の検索
        # P-001の 2026-10-02 00:00 (since: 含む) から 2026-10-04 00:00 (until: 含まない) まで
        since_time = datetime(2026, 10, 2, 0, 0, tzinfo=jst)
        until_time = datetime(2026, 10, 4, 0, 0, tzinfo=jst)

        inspections = ledger.query_inspections(
            pipe_id="P-001", since=since_time, until=until_time
        )

        print("--- 検索結果 ---")
        for item in inspections:
            print(
                f"管路番号: {item.pipe_id} | 点検日時: {item.inspected_at} | 状態: {item.condition} | 備考: {item.note}"
            )

        # 4. CSV出力
        # P-001の点検履歴を指定のファイルパスに出力する
        result = ledger.export_csv(
            destination=str(output_csv_path), pipe_ids=["P-001"]
        )

        print(f"Exported: {result.rows_written} 件")

    except Exception as e:
        print(f"エラーが発生しました: {e}")
    finally:
        # 処理終了時には適切に接続を終了する
        ledger.close()


if __name__ == "__main__":
    main()
実行結果
--- 検索結果 ---
管路番号: P-001 | 点検日時: 2026-10-02 10:00:00+09:00 | 状態: 2 | 備考: 軽微な劣化
管路番号: P-001 | 点検日時: 2026-10-03 10:00:00+09:00 | 状態: 4 | 備考: 要経過観察
Exported: 2 件

実行結果

生成されたプログラムの実行結果を比較します。

条件 実行回数 成功回数 成功率
A:マニュアルのみ 5 5 100%
B:サンプルコードのみ 5 5 100%
C:マニュアル+サンプル 5 5 100%
合計 15 15 100%

今回の検証では、すべてのプログラムが正常に実行されました。

また、表記の誤差はあれど実行結果も同じでした。

管路番号: P-001
点検日時: 2026-10-02 10:00:00+09:00
点検状態: 2
備考: 軽微な劣化

管路番号: P-001
点検日時: 2026-10-03 10:00:00+09:00
点検状態: 4
備考: 要経過観察

CSV出力件数: 2件

少なくとも今回の開発依頼については、マニュアルだけでも、サンプルコードだけでも、目的のプログラムを生成できたことになります。

コード

マニュアルのみの場合

日本時間の指定には次のようなコードが使われていました。

from datetime import datetime, timezone, timedelta

jst = timezone(timedelta(hours=9))

マニュアルには、日本時間をどのように表現するかまでは書かれていません。

それでも、Pythonの標準ライブラリを利用してUTC+9のタイムゾーンを作成しています。

また、点検履歴の登録についても、3件のデータを個別に登録する方法や、辞書のリストにまとめてループで登録する方法など、複数の実装パターンが生成されました。

マニュアルに記載されたAPIの仕様を読み取り、開発依頼に合わせて実装方法を組み立てていることが分かります。

サンプルコードのみの場合

日本時間の指定にはサンプルコードに記載された ZoneInfo を利用する実装が見られました。

from zoneinfo import ZoneInfo

jst = ZoneInfo("Asia/Tokyo")

また、サンプルコードの構造を維持しながら、登録データや検索条件を変更しているプログラムもありました。

一方、サンプルコードに明示されていない属性については、次のような実装も見られました。

note = getattr(item, "note", "")

これは、属性が存在するか分からない場合に備えた実装です。

マニュアルには Inspection の属性として note が明記されていますが、サンプルコードだけでは、その情報を直接確認できません。

このようにサンプルコードだけの場合は、マニュアルだけの場合とは異なる判断が見られました。

マニュアル+サンプルコードの場合

生成されたプログラムは、マニュアルに記載されたAPI仕様に従いつつ、サンプルコードに近い構造を採用しているものが多く見られました。

ただし、今回の検証では、マニュアルのみの場合と比較して、実行成功率が向上したわけではありません。

少なくとも今回の検証では、サンプルコードを追加することで、明確な実行結果の改善は確認できませんでした。

考察

今回の検証結果から、いくつかのことが分かりました。

マニュアルだけでも実装できる

今回の検証では、マニュアルのみで5回すべて正常に動作するプログラムが生成されました。

これは、生成AIがAPIの説明を読み取り、引数や戻り値、呼び出し順序を理解して、実装に利用できることを示しています。

人間が実装する場合(少なくとも私が実装する場合)、初めて利用するライブラリでは、サンプルコードを探すことが重要でした。

しかし、生成AIを利用するとマニュアルがあれば、サンプルコードがなくても難なく実装できました。

サンプルコードの価値がなくなったわけではない

今回の検証では、サンプルコードを追加しても実行成功率は変わりませんでした。

しかし、これはサンプルコードが不要であることを意味するわけではありません。

今回のマニュアルには、APIの引数や戻り値だけでなく、例外や制約事項まで詳しく記載されていました。

つまり、マニュアル自体がかなり充実していたということです。

マニュアルに書かれていない初期化手順や複数APIの組み合わせ方、実務上の注意点などがサンプルコードにしか存在しない場合は、結果が変わる可能性があります。

おわりに

今回の結果だけを見ると、十分に整備されたマニュアルがあれば、生成AIはサンプルコードなしでもプログラムを作成できると言えそうです。

ただし、実行できることと、要件を完全に満たすことは同じではありません。
生成されたコードのレビューや、境界値を含めたテストは引き続き必要です。

生成AIの進歩によって、プログラミングに必要な資料や開発手順も変わっていくのかもしれません。

今後も、生成AIがどのような情報を必要とし、どの程度正確にプログラムを生成できるのか、検証を続けていきたいと思います。


CSV出力に関する補足

実はライブラリの仕様にバグがありました。

PipeLedgerの export_csv() には、検索APIのような期間指定の引数がありません。
この為、

### 2.4 CSV出力
検索結果と同じ条件に該当する点検履歴をCSVファイルに出力する。

が実装できません。

生成されたコードでは何事もなく期間指定をせずに出力しています。
この点は実装時に指摘して欲しかったです。

ライブラリの仕様により実装出来ない機能を指摘してもらうようにプロンプトを書けば良かったです。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?