---
name: zenn-style
description: 監査レポートを Zenn 技術記事向けの文体 (だ/である調 + 比較表 + 階層化された見出し) に整えるスキル。`src/reporter.ts` の骨組みを LLM が整形してレポート (`out/*.md`) を仕上げるときに読み込む。
allowed-tools: read_file, write_file
---

# 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 の依存 foo-lib@2.1.0 が 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. 観点名`) を壊さず、**各観点セクション内に `###` サブ見出しを追加** して読みやすくする。

```text
# {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 × 件数 × 修正状況

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

```markdown
| 観点 | 判定 | 備考 |
|---|---|---|
| ライセンス | ✅ 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 行の補足を添える。

```markdown
- **[critical]** `license` — ライセンスと依存の整合性が崩れている
  - 根拠: メインは Apache-2.0 だが、package.json の依存 foo-lib@2.1.0 が 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 の適用は完了とみなす。