# Annotate Source Files > 正しい言語固有のコメントプレフィックスを使用して、ソースファイルにPUTワークフロー アノテーションを追加する。アノテーション構文、put_generate()によるスケルトン 生成、複数行アノテーション、.internal変数、バリデーションをカバーする。 30以上の言語をサポートし、自動コメントプレフィックス検出を備える。 コードベースを分析してアノテーション計画を持った後、新規または既存のソースファイルに ワークフロードキュメントを追加する時、データパイプライン、ETLプロセス、 複数ステップの計算をドキュメント化する時に使用する。 - Skill: `pjt222/annotate-source-files-3` (Agent Skill) - Install (CLI): `npx skillmds@latest add pjt222/annotate-source-files-3` - Raw SKILL.md: https://api.skillmd.com/api/skills/pjt222/annotate-source-files-3/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Data & Analytics - License: MIT - Author: pjt222 (https://skillmd.com/u/pjt222) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/pjt222/annotate-source-files-3 --- # ソースファイルのアノテーション putiorが構造化ワークフローデータを抽出してMermaidダイアグラムを生成できるように、ソースファイルにPUTワークフローアノテーションを追加する。 ## 使用タイミング - `analyze-codebase-workflow`でコードベースを分析してアノテーション計画を持った後 - 新規または既存のソースファイルにワークフロードキュメントを追加する時 - 自動検出されたワークフローを手動ラベルと接続で強化する時 - データパイプライン、ETLプロセス、複数ステップの計算をドキュメント化する時 ## 入力 - **必須**: アノテーションするソースファイル - **必須**: アノテーション計画またはワークフローステップの知識 - **任意**: スタイルの好み: 単一行または複数行（デフォルト: 単一行） - **任意**: スケルトン生成に`put_generate()`を使用するかどうか（デフォルト: はい） ## 手順 ### ステップ1: コメントプレフィックスを確認する 各言語にはPUTアノテーション用の特定のコメントプレフィックスがある。正しいものを見つけるには`get_comment_prefix()`を使用する。 ```r library(putior) # Common prefixes get_comment_prefix("R") # "#" get_comment_prefix("py") # "#" get_comment_prefix("sql") # "--" get_comment_prefix("js") # "//" get_comment_prefix("ts") # "//" get_comment_prefix("go") # "//" get_comment_prefix("rs") # "//" get_comment_prefix("m") # "%" get_comment_prefix("lua") # "--" ``` **期待結果:** `"#"`、`"--"`、`"//"`、`"%"`のような文字列。 > **行コメントとブロックコメント:** putiorは行コメント（`//`、`#`、`--`）とCスタイルのブロックコメント（`/* */`、`/** */`）の両方でアノテーションを検出する。JS/TSでは`//`と`/* */`ブロックの両方がスキャンされる。Pythonのトリプルクオート文字列（`''' '''`）は検出**されない** — Pythonアノテーションには`#`を使用する。 **失敗時:** 拡張子が認識されない場合、ファイルの言語がサポートされていない可能性がある。完全なリストは`get_supported_extensions()`で確認する。サポートされていない言語の場合、規約上のデフォルトとして`#`を使用する。 ### ステップ2: アノテーションスケルトンを生成する 自動検出されたI/Oに基づいてアノテーションテンプレートを作成するために`put_generate()`を使用する。 ```r # Print suggestions to console put_generate("./src/etl/") # Single-line style (default) put_generate("./src/etl/", style = "single") # Multiline style for complex annotations put_generate("./src/etl/", style = "multiline") # Copy to clipboard for pasting put_generate("./src/etl/", output = "clipboard") ``` Rファイルの出力例: ```r # put id:'extract_data', label:'Extract Customer Data', input:'customers.csv', output:'raw_data.internal' ``` SQLの出力例: ```sql -- put id:'load_data', label:'Load Customer Table', output:'customers' ``` **期待結果:** ソースファイルごとに1つ以上のアノテーションコメント行、検出された関数名とI/Oで事前入力されている。 **失敗時:** 提案が生成されない場合、ファイルに認識可能なI/Oパターンが含まれていない可能性がある。コードの理解に基づいて手動でアノテーションを書く。 ### ステップ3: アノテーションを精緻化する 生成されたスケルトンを編集して正確なラベル、接続、メタデータを追加する。 **アノテーション構文リファレンス:** ```text put id:'unique_id', label:'Human Readable Label', input:'file1.csv, file2.rds', output:'result.parquet, summary.internal' ``` フィールド: - `id`（必須）: 一意の識別子、ノード接続に使用 - `label`（必須）: ダイアグラムに表示される人間可読な説明 - `input`: カンマ区切りの入力ファイルまたは変数のリスト - `output`: カンマ区切りの出力ファイルまたは変数のリスト - `.internal`拡張子: メモリ内変数を示す（スクリプト間で永続化されない） - `node_type`: Mermaidノードの形状とクラススタイルを制御する。値: - `"input"` — スタジアム形状`([...])`、データソースと設定用 - `"output"` — サブルーチン形状`[[...]]`、生成されたアーティファクト用 - `"process"` — 矩形`[...]`、処理ステップ用（デフォルト） - `"decision"` — ダイヤモンド`{...}`、条件ロジック用 - `"start"` / `"end"` — スタジアム形状`([...])`、開始/終端ノード用 `node_type`の例: ```r # put id:'config', label:'Load Config', node_type:'input', output:'config.internal' # put id:'transform', label:'Apply Rules', node_type:'process', input:'config.internal', output:'result.rds' # put id:'report', label:'Generate Report', node_type:'output', input:'result.rds' ``` **複数行構文**（複雑なアノテーション用）: ```r # put id:'complex_step', \ # label:'Multi-line Label', \ # input:'data.csv, config.yaml', \ # output:'result.parquet' ``` **ファイル間データフロー**（ファイルベースI/Oによるスクリプト間接続）: ```r # Script 1: extract.R # put id:'extract', label:'Extract Data', output:'raw_data.internal, raw_data.rds' data <- read.csv("source.csv") saveRDS(data, "raw_data.rds") # Script 2: transform.R # put id:'transform', label:'Transform Data', input:'raw_data.rds', output:'clean_data.parquet' data <- readRDS("raw_data.rds") arrow::write_parquet(clean, "clean_data.parquet") ``` **期待結果:** 実際のデータフローを反映する正確なID、ラベル、I/Oフィールドでアノテーションが精緻化される。 **失敗時:** I/Oが不確かな場合、メモリ内の中間物には`.internal`拡張子を使用し、永続化データには明示的なファイル名を使用する。 ### ステップ4: ファイルにアノテーションを挿入する 各ファイルの先頭または関連するコードブロックの直上にアノテーションを配置する。 **配置規約:** 1. **ファイルレベルアノテーション**: ファイルの先頭に配置、shebang行やファイルヘッダーコメントの後 2. **ブロックレベルアノテーション**: 記述するコードブロックの直上に配置 3. **ファイルあたり複数のアノテーション**: 異なるワークフローフェーズを持つファイルに使用 Rファイルでの配置例: ```r #!/usr/bin/env Rscript # ETL Extract Script # # put id:'read_source', label:'Read Source Data', input:'raw_data.csv', output:'df.internal' df <- read.csv("raw_data.csv") # put id:'clean_data', label:'Clean and Validate', input:'df.internal', output:'clean.rds' df_clean <- df[complete.cases(df), ] saveRDS(df_clean, "clean.rds") ``` Editツールを使用して、周囲のコードを乱さずに既存ファイルにアノテーションを挿入する。 **期待結果:** 各ソースファイルの適切な場所にアノテーションが挿入される。 **失敗時:** アノテーションがエディターのシンタックスハイライトを壊す場合、コメントプレフィックスが言語に対して正しいことを確認する。PUTアノテーションは標準コメントであり、コードの実行に影響しないはずである。 ### ステップ5: アノテーションを検証する putiorのバリデーションを実行してアノテーション構文と接続性を確認する。 ```r # Scan annotated files workflow <- put("./src/", validate = TRUE) # Check for validation issues print(workflow) cat(sprintf("Total nodes: %d\n", nrow(workflow))) # Verify connections by checking input/output overlap inputs <- unlist(strsplit(workflow$input, ",\\s*")) outputs <- unlist(strsplit(workflow$output, ",\\s*")) connected <- intersect(inputs, outputs) cat(sprintf("Connected data flows: %d\n", length(connected))) # Generate diagram to visually inspect cat(put_diagram(workflow, theme = "github", show_source_info = TRUE)) # Merge with auto-detected for maximum coverage merged <- put_merge("./src/", merge_strategy = "supplement") cat(put_diagram(merged, theme = "github")) ``` **期待結果:** すべてのアノテーションがエラーなくパースされる。ダイアグラムが接続されたワークフローを示す。`put_merge()`が自動検出からギャップを埋める。 **失敗時:** よくあるバリデーションの問題: - 閉じクオートの欠落: `id:'name` → `id:'name'` - 内部でのダブルクオートの使用: `id:"name"` → `id:'name'` - ファイル間の重複ID: 各`id`はスキャンされたディレクトリ全体で一意でなければならない - 誤った行でのバックスラッシュ継続: `\`は改行前の最後の文字でなければならない **Block comment syntax** (for `//`-prefix languages only: JS, TS, Go, Rust, C, C++, Java, etc.): Languages that use `//` for line comments also support PUT annotations inside `/* */` and `/** */` block comments. Use `* put` as the line prefix inside the block body: ```javascript /* put id:'init', label:'Initialize Config', output:'config.internal' */ /** * put id:'process', \ * label:'Process Records', \ * input:'config.internal, records.json', \ * output:'results.json' */ function processRecords(config, records) { // ... } ``` JSDoc-style annotations are particularly useful when documenting workflow steps alongside API documentation: ```typescript /** * Transform raw sensor data into normalized readings. * put id:'normalize', label:'Normalize Sensor Data', input:'raw_readings.json', output:'normalized.parquet' */ export function normalizeSensorData(readings: SensorReading[]): NormalizedData { // ... } ``` > **Note:** Block comment annotations are **not** supported for `#`-prefix languages (R, Python, Shell) or `--`-prefix languages (SQL, Lua). Use only line comments for those languages. ## バリデーション - [ ] アノテーションされたすべてのファイルが構文的に有効なPUTアノテーションを持つ - [ ] `put("./src/")`が期待されるノード数のデータフレームを返す - [ ] スキャンされたディレクトリ全体で`id`値の重複がない - [ ] `put_diagram()`が接続されたフローチャートを生成する（すべてが孤立ノードではない） - [ ] 複数行アノテーション（使用する場合）がバックスラッシュ継続で正しくパースされる - [ ] `.internal`変数が出力としてのみ現れ、ファイル間入力としては現れない ## よくある落とし穴 - **クオートのネストエラー**: PUTアノテーションはシングルクオートを使用する: `id:'name'`。ダブルクオートはアノテーションが文字列コンテキスト内にある場合にパースの問題を引き起こす。 - **重複ID**: すべての`id`はスキャンスコープ内でグローバルに一意でなければならない。`