writer

---
name: writer
description: 'ASP.NET Core ハンドブックの新規章コンテンツを作成する。Use when: 新しい章を書く、ドキュメントを作成する、チャプターを追加する、コンテンツを執筆する。技術ドキュメントのライティング、ASP.NET Core ガイドの執筆。'
argument-hint: '作成する章のタイトルとセクション一覧を指定'
---

# ASP.NET Core ハンドブック ライタースキル

## 概要

このスキルは、`docs/` フォルダ内に新しい章のマークダウンドキュメントを作成するためのワークフローです。  
対象読者は **C# 以外の言語経験者** であり、日本語で記述します。

## 前提条件

- 言語: 日本語
- 対象読者: 他言語の経験者（対象言語・フレームワーク一覧は `.github/skills/languages.md` を参照）
- 対象バージョン: `.github/instructions/versioning.instructions.md` のバージョン決定ルールに従い、作成時点の最新バージョンを使用する

## 手順

### 1. 情報収集

以下の情報源を **必ず** 確認し、最新かつ正確な内容のみを記載する。

1. **MS Learn 公式ドキュメント** — ASP.NET Core や .NET 固有の概念だけでなく、一般的な IT 知識についても MS Learn を根拠とする
   - URL パターン: `https://learn.microsoft.com/en-us/aspnet/core/...?view=aspnetcore-N.0`（N はバージョン決定ルールで決定した番号）
   - マークダウン取得: URL に `&accept=text/markdown` を付与して `curl` で取得するとノイズが少ない
   - ロケール運用: **情報収集時は `en-us` の URL を使用し、章末の参考リンクとして記載する際は `ja-jp` の URL を使用する**
2. **他言語フレームワークの公式ドキュメント** — 比較情報を記載する際は、各フレームワークの最新ドキュメントを検索して正確性を確認する

### 2. 既存ドキュメントの形式確認

`docs/` フォルダ内の既存ファイル（例: `01-setup-dev-env.md`, `02-solutions-and-projects.md`）を読み、以下の形式要素を踏襲する。

#### ドキュメント構造

```markdown
# 第N章：タイトル

---

## 目次

1. [セクション1](#anchor)
   - [サブセクション](#anchor)
2. [セクション2](#anchor)
...

---

## 1. セクション1

### サブセクション

...

## N. 参考ドキュメント

- [タイトル | Microsoft Learn](URL)

---

*前の章: [第N-1章：タイトル](./NN-filename.md)*
*次の章: [第N+1章：タイトル](./NN-filename.md)*
```

#### 形式ルール

| 要素 | ルール |
| --- | --- |
| 見出し | `#` = 章タイトル、`##` = 大セクション（番号付き）、`###` = サブセクション、`####` = 小見出し |
| 目次 | ドキュメント冒頭に `## 目次` として内部アンカーリンク一覧を配置 |
| コードブロック | 言語指定必須（`csharp`, `xml`, `json`, `bash`, `text` など） |
| 図表 | Mermaid 記法で概念図・フローチャートを積極的に使用 |
| 注記 | `> [!TIP]`, `> [!NOTE]`, `> [!WARNING]` を適切に使い分け |
| テーブル | 比較情報や一覧はテーブルで整理 |
| 他言語比較 | `> [!TIP]` または `> [!NOTE]` ブロック内に記載 |
| 折りたたみ | IDE 別の手順は `<details><summary>` で折りたたむ |
| 参考リンク | 最終セクションに MS Learn 等の公式ドキュメントリンクを一覧化 |
| 前後リンク | ドキュメント末尾に前後の章へのリンクを配置 |

### 3. コンテンツ作成の原則

1. **初心者にわかりやすく** — 概念の説明は具体例とコードサンプルを交えて記述する
2. **実装サンプルを豊富に** — 可能な限り動作するコード例を記載し、コピー＆ペーストで試せるようにする
3. **最新バージョン準拠** — バージョン決定ルールで決定した .NET N / ASP.NET Core N に準拠し、古い API（Startup.cs 方式など）ではなく最新の Program.cs 方式で記載する
4. **最新 C# 機能の活用** — 対象バージョンに対応する最新の C# 言語機能を使用する
5. **MS Learn を根拠にする** — 独自の解釈や推測ではなく、公式ドキュメントの記載を根拠とする
6. **他言語比較を含める** — ASP.NET Core 特有の機能について、`.github/skills/languages.md` に記載の言語・フレームワークに対応する機能がある場合は NOTE として比較を記載する

### 4. 日本語表記ルール

- カタカナ語の長音符号: `.github/instructions/katakana.instructions.md` の辞書に従う
- 句読点: 「、」「。」を使用
- 専門用語: 初出時に英語を括弧で併記（例: 依存性注入 (Dependency Injection: DI)）

### 5. 品質チェック

コンテンツ作成後に以下を確認する。

- [ ] 目次のアンカーリンクが見出しと一致している
- [ ] コードブロックの言語指定が正しい
- [ ] Mermaid 図が正しい構文で記述されている
- [ ] MS Learn の URL が `?view=aspnetcore-N.0`（N は決定したバージョン番号）を含んでいる（ASP.NET Core 関連の場合）
- [ ] MS Learn の URL ロケール運用（情報収集は `en-us`、参考リンク掲載は `ja-jp`）が守られている
- [ ] テーブルの列数が揃っている
- [ ] 前後の章へのリンクが正しい
- [ ] `> [!TIP]` / `> [!NOTE]` / `> [!WARNING]` の使い分けが適切

## 出力先

- ファイルパス: `docs/NN-<slug>.md`（NN は章番号の 2 桁ゼロ埋め）
- ファイル名のスラッグ: 英語のケバブケース（例: `06-dependency-injection.md`）