// Markdownでの技術ドキュメント作成・更新のためのSKILL。Markdown形式を前提としており、*.mdファイルの差分を提案する場合は必ずロードする。
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | markdown.documentation |
| description | Markdownでの技術ドキュメント作成・更新のためのSKILL。Markdown形式を前提としており、*.mdファイルの差分を提案する場合は必ずロードする。 |
| license | MIT License |
| metadata | {"author":"@eaglesakura"} |
すべてのドキュメントには、以下のセクションを必ず含める：
${原則名}の補足」または「${規則名}の補足」とする${原則名}の実装例」または「${規則名}の実装例」とするコードブロックには、以下の2つの形式がある。AI Agentは、コードの種類に応じて適切な形式を選択する必要がある。
実在するコードベースからコードを引用する場合は、コードの場所をコメントとして記載する。
形式:
// ${パッケージ名}, ${ファイル名}.dart
// コード内容
記述ルール:
${パッケージ名}, ${ファイル名}.dart」とするpubspec.yamlのnameフィールドの値を使用する実装例:
// usecase_error, crash_report_request.dart
@freezed
abstract class CrashReportRequest with _$CrashReportRequest {
const factory CrashReportRequest({
required dynamic error,
}) = _CrashReportRequest;
}
新しいコード例やテンプレートを示す場合は、言語名を最初に記述する。
形式:
// コード内容
記述ルール:
dart、yaml、bash、text、typescript、jsonなどtextを使用する${変数名}）を使用して汎用的なコードを示す ```ファイルパス）は使用しない実装例:
/// ${機能の説明}.
abstract class ${機能名}Usecase {
static final provider = Provider<${機能名}Usecase>(
(ref) => throw UnimplementedError("$${機能名}Usecase is not implemented"),
);
/// ${メソッドの説明}.
Future<${機能名}Result> ${メソッド名}(${機能名}Request request);
const ${機能名}Usecase._();
}
重要: ファイルパスだけを記述した形式（ ```ファイルパス）は使用しない。必ず言語名（dart、yaml、bashなど）を最初に記述する。
ディレクトリ構成を記述する場合は、以下のルールに従う。
記述ルール:
textを使用する${変数名}）を使用して、汎用的な構成を示す形式:
${パス}/
├── ${ファイル名またはディレクトリ名}
│ └── ${ファイル名またはディレクトリ名}
└── ${ファイル名またはディレクトリ名}
実装例:
app_packages/usecase/
├── school/ # usecase_school（インターフェース）
│ ├── lib/
│ │ ├── usecase_school.dart # パッケージ名と同一
│ │ └── src/kanji_search/
│ │ ├── kanji_search_usecase.dart
│ │ ├── kanji_search_request.dart
│ │ └── kanji_search_result.dart
│ └── _impl/ # usecase_school_impl（実装）
│ └── lib/
│ ├── usecase_school_impl.dart # パッケージ名と同一
│ └── src/kanji_search_usecase/
│ └── kanji_search_usecase_impl.dart
└── injection/ # usecase_injection（依存注入）
└── lib/
├── usecase_injection.dart # パッケージ名と同一
└── src/
└── injection.dart
テンプレート変数の使用:
${変数名}形式のテンプレート変数を使用する${機能名}、${レイヤー名}、${画面名}などすべてのドキュメントには、末尾に「よくあるパターンとアンチパターン」セクションを配置する（必須）。
セクション構造:
## よくあるパターンとアンチパターン
### 推奨されるパターン
1. **${パターン名}**
* ${説明}
2. **${パターン名}**
* ${説明}
### 避けるべきパターン
1. **${パターン名}**
* ${説明}
2. **${パターン名}**
* ${説明}
記述ルール:
よくあるパターンとアンチパターン」とする1.）を使用する**${パターン名}**）で記述する*）で記述する##）として配置する###、####）として配置する##の次は###、###の次は####）推奨されるセクションの順序：
AI Agentがドキュメントを作成・更新する際は、以下の手順に従う：
既存コードの調査
ドキュメント構造の確認
コード参照の検証
リンターエラーの確認
整合性の確認
${変数名}）を使用する${機能名}、${レイヤー名}、${画面名}、${メソッド名}など例：dart、bash、text、yamlなど
ディレクトリ構成を示す場合はtextを使用する
tree コマンドの表示レイアウトを参考にする例
// dartのコードサンプル
void main() {
}
# ディレクトリ構造の表示サンプル
.cursor
├── agents
├── commands
├── mcp.json
├── rules
├── skills
└── worktrees.json
<URL>の形式で記述する
<https://docs.flutter.dev/ui/accessibility-and-internationalization/internationalization>*）を使用する-）を使用している箇所をアスタリスク（*）に変更するmermaidを指定するsequenceDiagramflowchartまたはgraphclassDiagramstateDiagram-v2実装例:
sequenceDiagram
actor User as ユーザー
participant View as View (Screen)
participant ViewModel as ViewModel
participant Usecase as Usecase/Delegate
User->>View: 画面操作（ボタンタップなど）
View->>ViewModel: onAction()
ViewModel->>Usecase: 処理を移譲
Usecase->>Usecase: 状態更新
Usecase-->>ViewModel: 処理結果
ViewModel-->>View: UI更新
View-->>User: 画面更新・遷移など
形式:
## 参考リンク
* ${リンクの説明}: <${URL}>
記述ルール:
参考リンク」とする*）で記述する<URL>）実装例:
## 参考リンク
* Flutter公式ドキュメント: <https://docs.flutter.dev/>
* Riverpod公式ドキュメント: <https://riverpod.dev/>
/）で区切る（Windows環境でも\ではなく/を使用する）良い例:
app_packages/usecase/school/lib/src/kanji_search_usecase.dartdocs/flutter/usecase.md悪い例:
/Users/example_user/work/path/to/repository/app_packages/usecase/school/lib/src/kanji_search_usecase.dart（絶対パス）app_packages\usecase\school\lib\src\kanji_search_usecase.dart（Windows形式の区切り文字）pubspec.yamlのnameフィールドの値を使用するusecase_school、usecase_school_impl、usecase_injection