dev-structured-logs

構造化ログ

レガシーなログ呼び出しと Serilog の JSON 設定に対して、慎重でレビューしやすい書き換えを実行します。デフォルトではドライランを行い、常に機械可読なプレビュー出力を生成します。

これは、決定論的なログ書き換えを行うための操作スキルです。一般的なバックエンドのオブザーバビリティや CI/CD のガイダンスを行うスキルとして使用しないでください。

ワークフロー

1. まずドライランを実行します：

python .codex/skills/dev-structured-logs/scripts/structured_logs.py --path <repo> --dry-run

2. 次を確認します：

• <repo>/patch.diff
• <repo>/preview-report.json

3. 確認後にのみ適用します：

python .codex/skills/dev-structured-logs/scripts/structured_logs.py --path <repo> --apply --backup-dir <dir>

4. 必要に応じてコミットします：

python .codex/skills/dev-structured-logs/scripts/structured_logs.py --path <repo> --apply --commit-msg "chore: structured logging migration"

タスクがサービス設計、ランタイムのオブザーバビリティ戦略、または API レイヤーのリファクタリングに広がる場合は、$software-csharp-backend に切り替えてください。 タスクが nuke/Build.cs や CI の実行変更に広がる場合は、$ops-nuke-cicd に切り替えてください。

CLI の契約

次のオプションをサポートしてください：

--path <repo>
[--dry-run]
[--apply]
[--preview-file <path>]
[--backup-dir <dir>]
[--enable-handler-scope]
[--handler-pattern <pattern>]
[--log-framework <serilog|microsoft|auto>]
[--exclude <glob>] (repeatable)
[--commit-msg "message"]

動作：

• --apply が指定されていない場合、デフォルトのモードはドライランです。
• CommandHandler のスコープ挿入はデフォルトで無効です。--enable-handler-scope で明示的に有効にしてください。
• 除外対象／生成フォルダー（bin/、obj/、node_modules/、packages/、.git/、.vs/）には触れないでください。
• リスクのある書き換えには、preview-report.json で risk_level と reason を設定してください。

パート 1：ログ変換ルール

メッセージ引数に次のいずれかを使用する logger.Log* および _logger.Log* 形式の呼び出しのみを書き換えてください：

• 文字列連結
• String.Format(...)
• 文字列補間（$"..."）

プロパティと引数リストを含むメッセージテンプレートに変換してください。 三項式を含む補間式は、引数式として保持してください。

次を保持してください：

• 例外オーバーロードの引数順序（LogError(ex, "...", args...)）
• 元の式の順序

メッセージ引数に副作用の可能性（メソッド呼び出し、new、インクリメント／デクリメント、複合代入）がある場合：

• ログ呼び出しの前に、式を一時変数に抽出してください
• レポートで変更を手動レビュー対象としてマークしてください

リスクの高い文をまたぐ書き換えは行わないでください。変更は呼び出し箇所に限定してください。

パート 2：CommandHandler のスコープルール

次のいずれかに該当するハンドラーを検出してください：

• ICommandHandler<T> を実装するクラス
• ハンドラーパターン（デフォルトは Handle|HandleAsync）に一致するパブリックメソッドで、最初のパラメーターをコマンドオブジェクトとして扱うもの

--enable-handler-scope が設定されている場合、メソッドの先頭にスコープがなければ挿入してください：

• コマンドのキーとなるプロパティから辞書を構築します：UserId、TransactionId、TransferId、VerificationId、SessionId、Id
• 次の例のように、コレクション初期化子形式でスコープ項目を初期化します：

var __scopeItems = new Dictionary<string, object>
{
    ["Property1"] = command.Property1
};

• using var _scope = _logger.BeginScope(__scopeItems); を使用します。

メソッドの先頭部分に、同等のコマンドプロパティを使用する BeginScope ブロックがすでにある場合はスキップしてください。

パート 3：Serilog の appsettings ルール

*.csproj のパッケージ参照に Serilog、Serilog.*、または Sc.Infrastructure.Serilog が含まれているかどうかで Serilog を自動検出してください。 いずれかの *.csproj ファイルにこれらのパッケージ名が含まれている場合、リポジトリを Serilog 対応として扱い、リポジトリ内のすべての appsettings.json ファイルに Serilog 設定の更新を適用してください。

Serilog が検出された場合は、リポジトリ内のすべての appsettings.json ファイルを調べてください。

オブジェクト形式の Args を持つ Serilog の File シンクごとに（Async → Logger → configureLogger → WriteTo など、ネストされた WriteTo パイプラインも含む）：

• Args.path が .json で終わるようにしてください
• Args.path がデバッグログファイルのパス（例：*.debug）の場合、.debug.json に変更してください
• Args.formatter を次の値に設定してください：
  • Sc.Infrastructure.Serilog.CustomJsonFormatter, Sc.Infrastructure.Serilog
• Args.outputTemplate を削除してください

File 以外のシンクは変更しないでください。 Serilog セクションまたは File シンクが存在しない場合は、何も行わないでください。

出力

リポジトリのルートに、常に次のファイルを生成してください：

• patch.diff の統合差分
• 次の項目を含む preview-report.json エントリ：
  • file
  • line
  • original
  • transformed
  • risk_level
  • reason

適用時：

• --backup-dir または .codex/skills/dev-structured-logs/backups にバックアップを作成します
• ファイルの更新を適用します
• --commit-msg が指定されている場合は、git commit を試みます

例

動作を検証するには、examples/ 内のファイルを使用します。

• concatenation.before.cs / concatenation.after.cs
• string-format.before.cs / string-format.after.cs
• interpolation.before.cs / interpolation.after.cs
• side-effect.before.cs / side-effect.after.cs
• handler-scope.before.cs / handler-scope.after.cs
• appsettings.before.json / appsettings.after.json