テクニカル記事
AIエージェントが、フォーマルな言語、一貫性のある構造、正確な用語、実用的な例、検証可能な参考文献を使用して、テクニカル記事を作成、改訂、レビューするための指示。
1. 利点
-
一貫性
安定した記事の文法により、テクニカルコンテンツがトピック間で予測可能になり、読者は文書構造を再学習することなく、定義、カテゴリ、原則、例、参考文献を見つけることができます。
-
可読性
簡潔な定義パラグラフ、明示的な見出し、用語定義リストにより、技術的な正確性を維持しながら認知負荷を軽減します。
-
ナビゲーションの容易さ
手動で管理された階層的な目次と番号付き見出しは、概念的な階層を明らかにし、長い記事に対して直接的なナビゲーションを提供します。
-
再利用性
分類法、用語リスト、実用的な例、出典が明らかな参考文献により、各記事は導入としても、耐久性のあるエンジニアリングリファレンスとしても有用です。
-
レビュー容易性
決定的なフォーマットとエビデンスルールにより、レビュアーは構造上の欠陥、言語上の欠陥、技術的な不正確さを分離できます。
2. 原則
2.1. 言語
-
フォーマル
ソフトウェアエンジニア、システムエンジニア、セキュリティ専門家、技術的な意思決定者に適した中立的な英語を使用します。
-
百科事典的
実践方法を規定する前に主題を定義します。推奨事項を提示する前に、概念が何であるか、どのように分類されるか、どこで適用されるかを説明します。
-
正確
広範または宣伝的な表現よりも、ドメイン固有の名詞と動詞を優先します。標準、仕様、プロトコル、ツール、フレームワーク、プラクティス、メトリクス、アーキテクチャパターンを区別します。
-
非人称的
第三人称または非人称構文を優先します。一人称のナレーション、直接的な二人称の呼びかけ、修辞的な質問、会話的なフィラーを避けます。
-
宣言的
定義、関係、制約、結果を直接述べます。実際の要件、推奨、可能性、不確実性を表現する場合にのみ、法助動詞を使用します。
2.2. コンテンツの完全性
-
エビデンス
外部で検証可能な主張は、権威ある情報源で裏付けます。標準化団体、公式ドキュメント、一次研究、正規のリポジトリを優先します。
-
最新性
時間に依存する事実、バージョン固有の動作、パフォーマンスしきい値、法的要件、製品機能は、含める前に検証します。
-
範囲
各記事を1つのテクニカルサブジェクトに集中させます。重要な背景資料を重複させるのではなく、隣接する記事へのリンクを貼ります。
-
分類の一貫性
概念は、一度に1つの明示的な分類軸でグループ化します。セクションが関係性を説明していない限り、ツール、プラクティス、成果、プロパティを同列に混在させないでください。
-
例
構文的に有効で、技術的に妥当であり、先行する説明に直接関連する例を使用します。
3. 構造
3.1. ファイルとタイトル
-
ファイル名
小文字のケバブケースで、主題を識別するファイル名を使用します。例：
technical-debt.md、feature-flags.md、file-systems.md。 -
フロントマター
対象リポジトリが明示的に要求していない限り、記事ファイルにYAMLフロントマターを追加しないでください。
-
H1タイトル
正確に1つのH1見出しで始め、タイトルケースで正規のサブジェクト名を含めます。
# Feature Flags
3.2. はじめに
H1見出しの直後に、1つまたは2つの簡潔な段落を配置します。
-
定義
最初の文で主題を定義します。その記事のドメインで普遍的に自明でない場合は、初出時に頭字語を展開します。
-
背景
主題の目的、運用上の役割、またはソフトウェアエンジニアリングとの関係を説明します。目次の前に詳細な分類法を導入しないでください。
例：
# Feature Flags
フィーチャーフラグは、新しいデプロイメントを必要とせずにアプリケーションの動作を有効または無効にするランタイム制御です。コードのデプロイメントと機能のリリースを分離し、管理されたロールアウト、実験、運用上の緩和をサポートします。
3.3. 目次
はじめの後、最初のH2セクションの前に、手動で管理されたMarkdownの目次を挿入します。
-
階層
番号付きのH2、H3、および重要なH4見出しをすべて、レベルごとに2スペースのインデントを使用して反映します。
-
ラベル
完全な数字のプレフィックスと見出しテキストを含めます。
-
アンカー
GitHub互換の小文字アンカーを使用します。GitHubの見出しルールに従って句読点を削除し、単語間のハイフンは保持します。
-
完全性
見出しが変更されるたびに、目次エントリを追加、削除、または名前変更します。
例：
- [1. カテゴリ](#1-カテゴリ)
- [1.1. デプロイメント戦略](#11-デプロイメント戦略)
- [1.1.1. ブルーグリーンデプロイメント](#111-ブルーグリーンデプロイメント)
- [1.1.2. カナリアデプロイメント](#112-カナリアデプロイメント)
- [2. 原則](#2-原則)
- [3. ベストプラクティス](#3-ベストプラクティス)
- [4. 用語](#4-用語)
- [5. 参考文献](#5-参考文献)
3.4. 番号付きセクション
H1より下のすべての記事見出しで、アラビア数字による10進数表記を使用します。
-
H2
トップレベルのセクションには
## 1. <セクション>を使用します。 -
H3
第2レベルのセクションには
### 1.1. <サブセクション>を使用します。 -
H4
サブセクションに別のレベルを必要とする実質的な分類法が含まれている場合にのみ、
#### 1.1.1. <トピック>を使用します。 -
深さ
H1を含めて4レベル以下の見出しレベルを推奨します。過度な見出しの深さは、用語定義リストまたは表に置き換えてください。
-
標準セクション
サブジェクトに貢献するセクションのみを選択します。一般的なコーパス互換ラベルには、
利点、カテゴリ、原則、ベストプラクティス、用語、参考文献があります。 -
順序
基礎となる概念とカテゴリから始め、原則またはプラクティスに進み、最後に用語と参考文献で締めくくります。
3.5. 分類法と定義
概念的な移行には散文を使用し、スキャン可能なテクニカルコンテンツには用語定義リストを使用します。
-
セクションリード
主要なセクションを、分類の軸またはセクションの目的を説明する1つまたは2つの段落で開きます。
-
用語定義パターン
テクニカルラベルを箇条書きで、その説明を字下げされた引用ブロックで提示します。
- Atomicity > Atomicityは、トランザクションが1つのユニットとして完了するか、部分的な結果を保持せずにロールバックすることを保証します。 -
グループ化パターン
サブセクションに、規約、例、ツールなど、いくつかの異なるビューが含まれている場合、順序付きリストアイテムをローカルグループの見出しとして使用します。
-
ラベルの大文字小文字
概念的なラベルにはタイトルケースを、説明には文の先頭のみ大文字を使用します。
-
説明の質
用語の役割、動作、または定義特性で説明を始めます。意味を追加せずにラベルを繰り返す循環定義を避けます。
3.6. 例とデータ
-
スタンドアロン例
散文レベルのスタンドアロン例は
Example:で導入します。例と説明などのグループ化されたサブセクション内では、代わりに説明的な例ラベルを使用します。 -
コード例
最も正確な言語識別子を持つフェンス付きコードブロックを使用します。
-
インライン構文
コマンド、ファイルパス、設定キー、識別子、リテラル、短い構文断片にはバッククォートを使用します。
-
表
コンパクトな比較、マトリックス、メトリクス、コマンド、または列挙された参照データにはMarkdownテーブルを使用します。セルコンテンツを並列に保ち、セル内での散文段落を避けます。
-
図
関係やフローを散文や表で効率的に説明できない場合は、Mermaidなどのテキストベースの図を使用します。
-
注意書き
制約、注意事項、クロスリンク、または解釈を実質的に変更する情報には、GitHubの注意書きを控えめに使用します。
> [!NOTE] > メトリクスのしきい値は、引用されたレポート期間に依存するため、公開前に検証する必要があります。
3.7. 参考文献
すべての記事は、番号付きの 参考文献 セクションで終了します。
-
内部参考文献
関連するSentenzの記事には、リポジトリ相対リンクを使用します。
- Sentenz [バージョニング](../articles/versioning.md) の記事。 -
外部参考文献
リンクされたタイトルの前に組織または発行元を記載し、リンクの後にソースタイプを特定します。
- NIST [Secure Software Development Framework (SSDF) Version 1.1](https://csrc.nist.gov/pubs/sp/800/218/final) 公開文書。 - Kubernetes [ドキュメント](https://kubernetes.io/docs/) ドキュメント。 - GitHub [DORA Four Keys](https://github.com/dora-team/fourkeys) リポジトリ。 -
ソースタイプ
記事、ドキュメント、ページ、公開文書、リポジトリ、レポート、仕様、標準などの正確な修飾子を使用します。 -
関連性
記事で引用または実質的に使用されたソースのみを含めます。記事の主張に関係のない一般的な読書リストを作成しないでください。
4. ワークフロー
4.1. 作成
-
調査
対象の記事ディレクトリ内の隣接するファイルを読みます。ローカルの見出しの語彙、リンクスタイル、コードフェンスの規則、関連する内部記事を記録します。
-
範囲
記事の主題、意図する深さ、主要な分類の軸を定義します。隣接する主題は、相互リンクされた記事に分離します。
-
調査
信頼できる一次情報源を収集します。用語、標準、メトリクス、製品の動作、時間に依存する詳細を検証します。
-
アウトライン
必要な標準セクションを選択し、散文を起草する前に番号付き見出し階層を構築します。
-
テンプレートの読み込み
新しい記事を作成するときは
assets/technical-article-template.mdを読み込みます。サブジェクトに貢献しないセクションは削除します。 -
導入の起草
H1タイトルと1つまたは2つの定義段落を書きます。実装の詳細を先に詰め込まずに、主題とエンジニアリングのコンテキストを確立します。
-
目次の構築
計画された見出し階層を反映し、正確なGitHub互換アンカーを生成します。
-
セクションの作成
セクションリード、用語定義リスト、例、表、図、注意書きは、理解を向上させる場合にのみ追加します。
-
参考文献の追加
内部相対リンクと外部ソース修飾された参考文献を追加します。すべての実質的な外部主張に適切な権威ある情報源があることを確認します。
-
検証
記事を返すかコミットする前に、すべての 品質ゲート を適用します。
4.2. 改訂
-
意図を保持
構造を変更する前に、既存の記事の主題、範囲、分類法を特定します。
-
テンプレートの読み込み
記事を改訂する前に
assets/technical-article-template.mdを読み込みます。構造的なベースラインとして使用し、該当しないテンプレートセクションは削除し、有効な記事固有のセクションは保持します。 -
診断
欠陥を、技術的な正確性、分類法、構成、言語、フォーマット、リンク、例、参考文献に分離します。
-
標準化
タイトル、導入、目次、番号付け、見出しレベル、リスト、引用ブロック、コードフェンス、参考文献をこのスキルに合わせます。
-
言語の洗練
曖昧で、繰り返しが多い、会話的、または宣伝的な表現を、直接的な技術的定義とドメインに適した動詞に置き換えます。
-
ナビゲーションの調整
見出しまたはファイル名が変更されるたびに、アンカー、クロスリンク、参考文献を更新します。
-
検証
すべての品質ゲートを再実行し、改訂によって明示的な理由なしに技術的に関連する情報が削除されていないことを確認します。
4.3. レビュー
-
テンプレートの読み込み
記事をレビューする前に
assets/technical-article-template.mdを読み込みます。構造的なベースラインとして使用し、省略されたオプションのセクションを、その欠如が完全性または一貫性の問題を引き起こさない限り、欠陥として報告しないでください。 -
評価
次の順序で記事をレビューします。
- 技術的正確性
- 範囲と分類の一貫性
- 構造の準拠
- 用語と頭字語
- 例、表、図
- リンクと参考文献
- 文法、句読点、可読性
-
所見の報告
影響を受ける見出しまたは行、欠陥、その技術的な結果、および具体的な修正とともに所見を報告します。スタイルの好みよりも、事実の誤りと構造的な不整合を優先します。
5. スタイルガイド
5.1. 声とトーン
-
現在形
定義、機能、現在のプラクティスには現在形を使用します。
-
過去形
過去形は、歴史的な出来事または置き換えられた動作にのみ使用します。
-
能動態
行為者またはメカニズムが重要な場合は能動態を優先します。
-
受動態
プロセスまたは結果に焦点があり、行為者が重要でない場合は受動態を使用します。
-
非人称の視点
一人称および二人称の代名詞を避けます。
-
専門性
業界で認められた用語を推奨します。比喩、冗談、または不必要な創造性を避けます。
5.2. 用語
-
一貫性
記事全体とコーパス全体で同じ用語を使用します。同義語を1つの記事内で切り替えないでください。
-
頭字語
初出時に定義し、記事全体で同じ短縮形を使用します。頭字語が記事全体で3回未満しか使用されていない場合は展開します。
-
新造語
必要で、すぐに定義されている場合を除き、新しい複合語または造語を導入しないでください。
-
商標
正しいスペル、大文字小文字、および帰属表示を使用します。商標を一般的な用語として使用しないでください。
5.3. 文と段落
-
長さ
文は1つの主張に、段落は1つのトピックに制限します。
-
移行
段落をつなぐために、移行表現またはトピックセンテンスを使用します。
-
複雑さ
埋め込み節を避け、従属関係を明示的にします。
-
並列性
リスト内および同じレベルの見出し内では、類似した構造を使用します。
5.4. リストと引用
-
箇条書きリスト
順序のない項目またはグループには箇条書きを使用します。
-
順序付きリスト
順序付きの手順または優先順位が明示されている場合は順序付きリストを使用します。
-
引用ブロック
引用、定義、または区別されたコンテンツには引用ブロックを使用します。引用ブロックをネストしないでください。
-
リストの句読点
各箇条書きの終わりにはピリオドを使用しません。各アイテムが完全な文の場合は、一貫してピリオドで終了します。
5.5. リンクと引用
-
インラインリンク
リンクテキストは説明的にし、「ここをクリック」や「詳細」のようなフレーズは避けます。
-
参照リンク
複数の場所で同じリンクターゲットが再利用される場合は、参照リンクを使用します。
-
引用の形式
記事内では括弧付きの数字参照
[1]を使用し、参考文献セクションでは完全なソースエントリをリストします。
サンプルの引用マッピング：
記事テキスト ... 実証されています [1]。
## 5. 参考文献
1. NIST [Secure Software Development Framework (SSDF) Version 1.1](https://csrc.nist.gov/pubs/sp/800/218/final) 公開文書。
5.6. コード、表、注意書き
-
コードブロック
複数行のコードまたは構成には、言語指定子を持つフェンス付きコードブロックを使用します。
-
インラインコード
シェルコマンド、ファイル名、キー、値、および識別子にはバッククォートを使用します。
-
表
比較データには表を使用します。セル内の複雑な散文を避けます。セルを空のままにしないでください。
-
注意書き
[!NOTE]、[!WARNING]、[!IMPORTANT]を適切に使用します。注意書きをネストしないでください。 -
図
Mermaid図は、関係を明確にする場合に使用します。図の前後に説明テキストを含めます。
6. 品質ゲート
各品質ゲートは、ゲートラベルで始まり、合格条件が続きます。
-
G1: ファイル名の規則
ファイル名は小文字のケバブケースで、
.md拡張子を持ちます。 -
G2: タイトル
正確に1つのH1見出しが存在し、記事の主題を正確に反映しています。
-
G3: 導入
H1の後に1つまたは2つの定義段落が続き、主題を確立しています。
-
G4: 目次
すべてのH2/H3/H4セクションを反映した、完全で正確な手動の目次が存在します。
-
G5: 番号付け
すべてのセクション見出しは、H1より下でアラビア数字の10進数番号を使用しています。
-
G6: 見出しの深さ
最大4レベルの見出し（H1を含む）が使用されています。深すぎる階層は使用されていません。
-
G7: 参考文献
番号付きの参考文献セクションが存在し、各参考文献にはリンクとソースタイプが含まれています。
-
G8: リンクの検証
すべての内部リンクと外部リンクは解決可能です。
-
G9: 言語
記事全体でフォーマルで正確な言語が使用されています。口語的な表現や主観的な表現はありません。
-
G10: 分類の一貫性
類似した概念は同じレベルの見出しまたはリストにグループ化されており、混合は避けられています。
-
G11: 例
すべての例は有効で、関連性があり、説明されています。
7. リソース
8. 参考文献
- このスキルは、正式で百科事典的なテクニカル記事を書くための一貫したガイドラインを提供します。