AGENTS.md - カスタムエージェント用プロジェクトガイドライン #

このドキュメントは、このプロジェクトで作業するカスタムエージェント向けのガイドラインです。

FUSHAGOYA - ブログ執筆ガイドライン（共通） #

プロジェクト概要 #

• ブログ名: FUSHAGOYA
• URL: https://fushagoya.com
• 著者: kohbis
• ブログの目的: SRE/DevOps、クラウドネイティブ技術、AWS、Kubernetesを中心とした技術知見の共有とイベント参加記録
• 想定読者（ペルソナ）: クラウドネイティブ技術やSREに興味のあるエンジニア、実践的な知見を求める開発者
• ブログのトーン/スタイル:
  • 丁寧語ベースだがカジュアルで親しみやすい表現を適度に使用
  • 主観的な視点を明確に示す（「個人的には〜」「〜だと思います」）
  • 実用的かつ技術寄り、読みやすさと親近感を重視
  • 失敗談や苦労したポイントを率直に記述し、学習姿勢を共有

執筆ルール #

1. 言語とスタイル #

• 常に日本語で執筆
• 段落は短めにし、1〜3文ごとに改行して読みやすくする
• 長い説明は、必要に応じてMarkdownのハード改行（行末に半角スペース2つ）でリズムよく区切る
• 基本は丁寧語だが、親しみやすさを重視したカジュアルな表現も適度に使用
  • 「ちょっと」「なんやかんや」「パッと」などの口語表現
  • 「お察しください」「〜ですね」など読者との距離を縮める表現
  • 「そんなわけで」「ちなみに」などの接続詞を活用
• 堅い表現よりカジュアルな表現を優先
  • 「習熟」→「得意」、「精通」→「詳しい」など
• 主観的な視点を明確に示す
  • 「個人的な〜」「自分なりの〜」「〜だと思います」
• 謙虚な姿勢を保つ
  • 「初心者過ぎて〜」「〜してみました」

2. 記事構成 #

イベントレポート記事 #

タイトル: 「[イベント名] に行ってきた」「〜に参加しました」
導入: 「〜に参加してきました。」
本文: 聴講セッションのメモとリンク
終了: 所感・まとめ

技術記事 #

導入: 背景・目的の説明
本文: 段階的な手順説明（説明 → 実例 → 解説 の流れ）
注意事項: 実用的な警告（「自己責任で」「課金注意」など）
終了: 「以上。」で簡潔に締める

学習記録 #

導入: 学習のきっかけ・動機
本文: 実際に試した内容・ハマったポイント
メモ: 個人的な気づき・備忘録
終了: 「〜していきたいです」で前向きに締める

OSSコントリビューション / コミュニティ参加記事 #

導入: 参加のきっかけ・出会い
本文: プロジェクト紹介、参加方法の案内（詳細は外部記事へ委譲）
所感: やってみてよかったこと
終了: 参加のハードルが低いことを伝え、読者に参加を促す

3. コードとコマンド #

• コードブロックを適切に使う（言語指定を必ず含める）
• 実際に使えるコードやコマンドを提供
• 環境や前提条件を明記
• エラーやハマりポイントも率直に記述
• 適宜コマンド例や設定例を示す

4. 専門用語と読者への配慮 #

• 専門用語には必要に応じて注釈を入れる
• 初心者でも理解できる構成を心がける
• 段階的で分かりやすい説明
• 注意書きの追加（課金、セキュリティ、動作環境など）

5. 引用と参考文献 #

• 参考にした記事やイベントを明確に記載
• Speaker Deck埋め込みを積極的に活用
• 外部リンクには適切な説明を付与

6. 区切り線の使用 #

• セクション分けには---を使用
• 重要な転換点で明確に区切る

コンテンツ構造 / フォルダ構成 #

ディレクトリ構造 #

/posts/YYYY/MM/         # 各記事のMarkdownファイル
/img/YYYY/記事名/       # 記事に関連する画像ファイル
/_data/metadata.json    # ブログ設定ファイル（サイトメタデータ）
/_includes/layouts/     # レイアウトテンプレート（Nunjucks）
/css/                   # スタイルシート
/js/                    # JavaScript

ファイル命名規則 #

• ファイル名： kebab-case.md形式
• 配置： posts/YYYY/MM/記事名.md
• 例： posts/2024/12/new-blog-post.md

Front Matter 形式 #

通常記事 #

---
title: "記事タイトル"
tags:
  - tag1
  - tag2
date: YYYY-MM-DD HH:MM:SS
layout: layouts/post.njk
---

外部記事リダイレクト用 #

---
title: "記事タイトル"
tags:
  - tag1
date: YYYY-MM-DD HH:MM:SS
external:
  site: medium  # qiita, medium, speakerdeck, zenn, hatena, gihyojp
  url: https://example.com/article
layout: layouts/redirect.njk
---

スライド埋め込み用 #

---
title: "記事タイトル"
tags:
  - slide
  - tag1
date: YYYY-MM-DD HH:MM:SS
external:
  site: speakerdeck
  url: https://speakerdeck.com/kohbis/slide-id
  embedCode: <script defer class="speakerdeck-embed" data-id="slide-id" data-ratio="1.7777777777777777" src="//speakerdeck.com/assets/embed.js"></script>
layout: layouts/post.njk
---

タグ管理 #

よく使用されるタグ（既存記事から抽出）:

• 技術系: aws, kubernetes, docker, terraform, ruby, rails, rust, golang, python, nodejs
• AWS関連: amazon-eks, amazon-ec2, amazon-rds, Lambda
• イベント系: report, slide, sre, sre-next
• その他: platform-engineering, observability, opentelemetry, prometheus, newrelic, argocd, keda

タグ付けルール:

• 技術系タグは小文字で統一
• イベントレポートには必ずreportタグを追加
• スライドには必ずslideタグを追加
• 個人的な記録はdiaryタグを検討
• 既存タグを優先的に使用し、統一性を保つ

サポートされるコンテンツタイプ #

• 外部記事統合（Qiita, Medium, Zenn, Speaker Deck等）
• Twitter埋め込み（カスタムショートコード `
  `）
• 画像管理（年・記事ごとのディレクトリ分割）

画像管理 #

• 画像は/img/YYYY/記事名/ディレクトリに配置
• 記事内では絶対パスで参照： ![alt text](/img/2024/article-name/image.png)

禁止／注意事項 #

1. 著作権とライセンス

   • 出典やライセンス違反になりそうなコード・文章の転載は禁止
   • 引用する場合は必ず出典を明記

2. セキュリティ

   • 個人情報や機密情報（APIキー、パスワード等）を掲載しないこと
   • セキュリティリスクのあるコード例は注意書きを追加

3. コード品質

   • 不要に長いコードのインライン化は避け、必要があればgistなどを使う
   • 実際に動作確認したコードのみを掲載

4. 品質管理ツール

   • 記事執筆後は必ずnpm run textlintでチェック
   • textlintエラーはnpm run textlint:fixで自動修正可能
   • .textlintrcに定義されたルールに従う
   • よくあるエラーと対処:
     • インラインコード前にスペースを入れない（ja-spacing/ja-space-around-code）
     • 100文字超の文は分割する（ja-technical-writing/sentence-length）
     • 「〜ないかと」は常体なので「〜ないでしょうか」「〜ないかと思います」に（jtf-style/1.1.1.本文）

5. 日付フォーマット

   • 必ずYYYY-MM-DD HH:MM:SS形式を厳守
   • 例： 2024-12-01 12:00:00

記事執筆後の評価・改善 #

記事を書き終えたら、以下の外部プロンプトを使って「評価→改善」を回す運用にします。

• ブログ記事評価プロンプト: https://gist.github.com/nwiizo/c75043438866100452fd249e536341d4

おすすめの流れ:

1. npm run textlint で日本語/表記を整える
2. 上記プロンプトで評価レポートを出してもらう
3. 指摘のうち、まずは「炎上リスク」「前提条件・制約」「再現手順」を優先して直す

毎回の投入テンプレは .ai-context/prompts/blog-article-evaluation.md を参照します。

開発コマンド #

# 開発サーバー起動
npm run serve

# ビルド
npm run build

# Lint（JavaScript/設定ファイル）
npm run lint
npm run lint:fix

# テキストLint（Markdown記事）
npm run textlint
npm run textlint:fix

技術スタック #

SSG (Static Site Generator) #

• Eleventy (11ty) v3.x
• テンプレートエンジン: Nunjucks
• 設定ファイル: .eleventy.js

言語・スタイル #

• JavaScript: ES Modules (type: "module")
• CSS: カスタムスタイル
• Markdown: 記事コンテンツ

デプロイ・品質管理 #

• デプロイ: Firebase Hosting
• Lint: ESLint (JS), textlint (Markdown)
• 品質チェック: textlint プリセット（日本語技術文書向け）

変更履歴 #

• 2024-11-29: 初版作成
• 2024-11-29: .ai-context/ による共通管理システムに移行
• 2024-12-17: 技術スタック情報を追加、overridesファイルの重複を整理

このガイドラインに従い、一貫性のある高品質な開発をサポートしてください。