peintangos/zenn-style

Zenn スタイル レポート文体スキル

このスキルを使うタイミング

• 監査レポート (out/mastra-audit-report.md) を生成する最終段で、src/reporter.ts が組んだ Markdown 骨組みを LLM が本文に整えるとき
• critic findings の要約を "技術記事らしい" ナラティブにまとめたいとき
• 5 観点の結果を 横並びで比較 したいとき (単なる箇条書きより比較表が読みやすい)

reporter.ts の generateAuditReport() は JSON を埋め込むだけの pure 関数なので、そのままでは読み物にならない。このスキルはその骨組みの テキスト化・ナラティブ化 フェーズを担当する。監査ロジック (何を検出すべきか) は skills/audit/* の担当であり、このスキルでは扱わない。

文体の三原則

1. だ/である調 (常体) を貫く

技術記事読者に速く読んでもらうため、丁寧語ではなく だ/である調 を使う。語尾が揺れると信頼感が落ちるので、一つのレポート内で混在させない。

| OK | NG | |---|---| | Elastic License 2.0 は SaaS 再配布に制約があるため、商用利用の観点で注意が必要だ。 | Elastic License 2.0 は SaaS 再配布に制約があるため、商用利用の観点で注意が必要です。 | | 依存関係に GPL-3.0 のライブラリが含まれている。 | 依存関係に GPL-3.0 のライブラリが含まれています。 | | CVE-2024-XXXX の修正 PR はマージ済みである。 | CVE-2024-XXXX の修正 PR はマージ済みになっております。 |

ただし 引用や固有名詞に含まれる敬体はそのまま 残してよい (例: ドキュメントからの直接引用、README の抜粋)。引用であることを > で明示する。

2. 結論 → 根拠 → 含意 の順で書く

Zenn 読者は斜め読みが前提。各セクションの冒頭 1〜2 行で結論を提示し、その後に根拠 (バージョン、コミット、issue 番号、ベンチマーク値) を置き、最後に実利への含意 (採用可否・代替案・運用上の注意) を添える。

パターン例:

1. 結論: ライセンス面では採用可能だ。 / ただし依存に AGPL-3.0 が混入しており、SaaS 配布時は要注意だ。
2. 根拠: GitHub メタデータの license.spdx_id は Apache-2.0 だが、package.json の依存 [email protected] が AGPL-3.0 で、2024-08 のリリース以降継続している。
3. 含意: SaaS として提供する場合、foo-lib を permissive な fork に差し替えるか、該当経路を切り出して動的リンクにする必要がある。

3. 主観語・過度な装飾を避ける

素晴らしい 非常に とても 驚くほど 革命的な のような主観的な形容は、技術監査レポートでは信頼性を削ぐ。具体的な数値、比率、バージョン、日付で代替する。

| 避ける表現 | 置き換え先 | |---|---| | メンテナンスは非常に活発だ | 直近 3 ヶ月で 42 件の PR がマージされ、週次リリースが維持されている | | セキュリティ面で優秀 | OSV に既知の未修正脆弱性は 0 件、CVSS 7.0 以上の履歴も過去 12 ヶ月で 0 件 | | コミュニティが盛り上がっている | GitHub stars 12.3k / fork 1.1k / 月間コントリビュータ 38 名 |

見出し構造

reporter.ts の骨組み (# タイトル → ## N. 観点名) を壊さず、各観点セクション内に ### サブ見出しを追加 して読みやすくする。

# {owner}/{repo} 監査レポート
## エグゼクティブサマリ
## 1. ライセンス
### 結論
### 根拠
### 含意
## 2. セキュリティ
### 結論
### 根拠
### 含意
... (5 観点分)
## 6. 整合性検証 (critic)
### Findings (severity 降順)

• # は 1 つだけ (レポートタイトル)。本文中に # を追加しない。
• ## は reporter.ts が既に出す固定枠。順序を入れ替えない。
• ### は自由に使ってよいが、結論 / 根拠 / 含意 の 3 段構成を目安に揃える。観点によっては ### 代替案 や ### 運用上の注意 を追加してよい。

比較表の使い方

Zenn スタイルでは Markdown テーブルが読みやすさの大きな武器になる。以下のシーンで 必ず テーブルを使う:

必ず表にするケース

1. 5 観点の総合判定サマリ: エグゼクティブサマリ直下に総覧テーブルを 1 つ置く
2. 依存ライブラリの商用利用可否: ライブラリ名 × ライセンス × 商用利用 × 備考
3. バージョン系列の比較: 安定版 / LTS / 最新 × リリース日 × 破壊的変更の有無
4. 脆弱性の severity 別件数: critical / high / medium / low × 件数 × 修正状況

総合判定サマリのテンプレート

| 観点 | 判定 | 備考 |
|---|---|---|
| ライセンス | ✅ OK | Apache-2.0、依存に懸念なし |
| セキュリティ | ⚠️ 注意 | CVE-2024-XXXX が未修正 |
| メンテナンス | ✅ OK | 週次リリース維持 |
| API 安定性 | ⚠️ 注意 | v2 系で破壊的変更あり |
| コミュニティ | ✅ OK | 月間コントリビュータ 38 名 |

絵文字記号 (✅ ⚠️ ❌) はステータス列に限って使用可とする。本文中にばら撒くと Zenn らしさが崩れる。

表にしないケース

• 観点ごとの長い説明 (→ 箇条書きまたは段落で書く)
• 1 行しかない情報 (→ インラインで書く)
• 自由記述の findings 本文 (→ 箇条書きで severity プレフィックス付き)

critic findings の書き換え

reporter.ts は critic findings をそのまま - **[critical]** aspect — message の形式で出力する。LLM はこれを受け取ったら、severity 順を 維持したまま 各 finding に 1〜2 行の補足を添える。

- **[critical]** `license` — ライセンスと依存の整合性が崩れている
  - 根拠: メインは Apache-2.0 だが、package.json の依存 [email protected] が AGPL-3.0。
  - 影響: SaaS 配布時に foo-lib のソース開示義務が連鎖する。
  - 対応: foo-lib を MIT の代替 (bar-lib) に置き換える、または動的リンク経路へ分離する。

- **[critical]** のプレフィックスは reporter.ts と厳密に一致させる。severity ラベルを 緊急 / 警告 のような日本語に翻訳してはいけない (機械可読性が落ちるため)。

NG 例 (ハマりやすいミス)

• 丁寧語と常体の混在: 〜である。〜です。〜だ。〜ます。 が 1 段落に混ざると、監査レポートとしての信頼感が消える。最終チェックで です ます ございます を grep して洗い出す。
• JSON ブロックを剥がす: reporter.ts が埋め込んだ ```json ... ``` は根拠として残す。本文を書き直すときに「読みやすさ」のために消してはいけない — 監査の再現性の根拠が消える。
• 主観的な推奨: 個人的にはおすすめです 筆者の経験では のような記述は監査レポートに混ぜない。推奨は必ず 数値・事実・契約 (ライセンス条文など) に紐づけて書く。
• 比較表に - と空欄を混ぜる: 空欄は "未調査" と誤読されやすい。値が無い場合は N/A または 未計測 と明示する。
• 絵文字を本文にばら撒く: ✅ ⚠️ は判定ステータスの列でのみ使う。本文や見出しに入れると Zenn 記事としての品格が落ちる。

出力契約

このスキルが適用された結果のレポートは src/reporter.ts の generateAuditReport() 骨組みを 拡張する 形で書かれる:

1. reporter.ts の # タイトル・## セクション順序・JSON ブロック・findings severity ラベルは 改変しない
2. 各 ## セクション内に ### サブ見出しを追加して結論/根拠/含意を構成する
3. エグゼクティブサマリ直下に 5 観点の総合判定テーブルを 1 つ追加する
4. critic findings の各項目に根拠 / 影響 / 対応 の 3 点を箇条書きで追加する
5. 文体は だ/である調で統一する

out/mastra-audit-report.md がこの 5 点を満たしていれば、Zenn スタイル skill の適用は完了とみなす。