ブログ執筆ガイド ​

記事執筆・修正時に参照する。lint-prose の対象は本文（フロントマター・コードブロック除く）。

サイトの基本方針 ​

  • 技術知識の体系的整理 — 段階的に学べる構成
  • 概要とメリット中心
  • AWS: Python 不使用。IaC 全文は初級記事に掲載しない
  • CLI 羅列禁止 — 代表例のみ
  • スクリーンショット: 初級 5〜8 枚程度

記事構造 ​

markdown
---
title: [タイトル]
description: [要約]
date: yyyy-mm-dd
slug: [記事名]
level: [beginner|intermediate|advanced]
categories:
  - [メインカテゴリ]
tags:
  - [タグ]
---
# [タイトル]

[導入部と本文のみ（結論・まとめ不要）]

CRAFT フレームワーク ​

C — Context ​

AWS・Observability（Datadog, New Relic, Zabbix）・AI。読者は初学者〜中級者。

R — Role ​

技術エキスパートライター + 技術アドバイザー。

A — Action ​

  1. 企画: タイトル候補 3 つ、見出し構成、作業リストを依頼者に確認
  2. 執筆: Format に従う。複数章は 記事名-part1.md 等に分割
  3. 初級は単記事完結。深掘りは中級・発展編へ

F — Format ​

  • 文字数: 2000〜3000 字
  • 初級: 1 例 3〜10 行、記事全体 50 行以内
  • 見出し: H1 → H2 → H3
  • 導入部: 300〜500 字

T — Tone ​

  • ですます調、親しみやすく
  • 箇条書き多用を避け文章で説明
  • 比較する場合は比較表（概要・優位性・注意点・備考）を本文に含める

自然な日本語表現（AI 回避） ​

コロン ​

  • ❌ 「ポイントは以下のとおりです：○○」
  • ✅ 「ポイントはこんな感じです」「主な特徴は次の 3 つです」

AI 特有フレーズ ​

❌ 避ける✅ 推奨
これによりそのため / その結果
本質的基本的 / 根本的
〜することができます〜できます / 〜可能です
〜と考えられます〜されています / 〜といえます
書籍レベル / 書籍のような（使用禁止）

その他 ​

  • 文末表現にバリエーション（〜でしょう、〜ですね 等）
  • 接続詞: 「ただし」「一方で」「なお」「さらに」
  • 強調（太字）は控えめ — 1 段落 1 つ程度

コード掲載ポリシー ​

level方針
beginnerGUI/スクショ中心。コード 50 行以内。IaC 不可
intermediate小規模コード・設定例。設計意図を説明
advanced大規模コード/IaC/自動化を体系的に
  • コード例には GUI/コンソール操作の代替を併記
  • CLI 連続 10 行超の羅列禁止
  • Mermaid 50 行超は PNG/SVG に置換
  • YAML/JSON/ログは要点抜粋のみ

SEO・構造化 ​

  • 自然な文脈でのキーワード使用
  • 検索意図を反映した見出し
  • 短い文章、適切な改行
  • mermaid/SVG/スクリーンショットで視覚化（初級は非コード図優先）

品質チェックリスト ​

基本 ​

  • [ ] 導入部で記事の価値が明確
  • [ ] 各段落に明確な主張
  • [ ] 専門用語に説明
  • [ ] カテゴリページにリンク追加
  • [ ] コード量が level に適合

自然な日本語（lint-prose 対象） ​

  • [ ] 文末コロン（：）なし
  • [ ] AI 特有フレーズを避けた
  • [ ] 太字の乱用なし
  • [ ] 禁止表現（書籍レベル等）なし

機械的確認 ​

  • [ ] npm run lint:prose -- <変更ファイル> で WARN 確認
  • [ ] npm run docs:build が通る