AGENTS.md
各エージェントはこのリポジトリで作業するときに必ずこのファイルを読むこと
目次
プロジェクト概要
Waka-DS.com ── ITコンサルタントによる技術ブログ。 Jekyll + jekyll-theme-yat で構築されたスタティックサイト。GitHub Pages でホストされている。
主なコンテンツ: Data Engineering・AI Agent 開発・SaaS 最適化など。
ディレクトリ構造
_posts/ 記事ファイル（日本語・英語とも置く）
_includes/ Liquid テンプレートのパーツ
_layouts/ ページレイアウト
_sass/ スタイルシート
_template/ 新規記事のテンプレート
_data/ サイトデータ（ナビなど）
assets/ 画像・CSS・JS
en/ 英語サイトのインデックス系ページ
記事ファイルの命名規則
_posts/YYYY-MM-DD-slug.md 日本語記事
_posts/YYYY-MM-DD-slug-en.md 英語記事（日本語と対になる場合）
- slug はハイフン区切りの英小文字
- 日英セットにする場合は、同じ slug を使い
-enサフィックスで英語版を作る
フロントマター
日本語記事
---
layout: post
title: "タイトル"
subtitle: サブタイトル（省略可）
categories: 開発
tags: ["タグ1", "タグ2"]
lang: ja
ref: slug-name # 日英対応させる場合のみ。英語版と同じ値にする
---
英語記事
---
layout: post
title: "Title"
subtitle: Subtitle (optional)
categories: Development
tags: ["tag1", "tag2"]
lang: en
ref: slug-name # 日本語版と同じ値
---
フィールドの注意点
titleに──以降のサブタイトル的な文言を含めない。タイトルはシンプルに保つsubtitleは省略してもよい。書く場合は記事の内容を短く補足するだけにする- NG:
〇〇・△△・□□まで体系的に解説/〇〇の使い方からCIでの活用法まで丁寧に解説 - OK:
Claude Code の Hooks・Ralph Loop の設計と実装（何が書いてあるかを素直に示す）
- NG:
refは日英対応が不要なら省略してよい
カテゴリ
カテゴリは以下のリストから選ぶ。リストにないものを使いたい場合は追加を提案すること（勝手に増やさない）。
日本語記事
| カテゴリ | 使いどころ |
|---|---|
開発 |
技術的な実装・ツール・言語・サービス全般 |
AI開発 |
AI・LLM・エージェント開発に特化した内容 |
データエンジニアリング |
データパイプライン・分析基盤・DB設計など |
インフラ |
クラウド・ホスティング・デプロイ・Docker など |
ブログ |
ブログ自体に関するメタな記事 |
英語記事
| Category | 使いどころ |
|---|---|
Development |
開発 の英語版 |
AI Development |
AI開発 の英語版 |
Data Engineering |
データエンジニアリング の英語版 |
Infrastructure |
インフラ の英語版 |
Blog |
ブログ の英語版 |
タグ
既存記事で使われているタグ。新規タグを追加する場合は既存のものと重複・類似していないか確認すること。
日本語タグ
AI開発, AIエージェント, AIネイティブ開発, AIセーフティ,
マルチエージェント, ハーネスエンジニアリング, コンテキスト管理,
自動化, 報酬ハッキング, アライメント,
Python, Docker, PostgreSQL, LLM,
データベース, バックエンド, 開発環境,
コードフォーマッター, コーディングエージェント,
ホスティング, フロントエンド, ドキュメント
英語タグ
Python, Docker, PostgreSQL, SQL, LLM,
Claude, Claude Code, Codex, Codex CLI, opencode, agmsg,
Supabase, Railway, Neon, Vercel, Netlify, Cloudflare,
BaaS, PaaS, Backend, Frontend,
OpenAPI, REST, API, Swagger,
Next.js, CLI, OSS,
GitHub Pages, Jekyll,
AI, AI-Native Development, Code Formatter,
Development Environment, Database,
Ralph Loop, Black, Alembic, SQLAlchemy, JSONB
文体・文章スタイル
基本方針
- 文体は常体（だ・である調）
- プレーンな文章を中心に書く。「引き」のある表現は記事全体で数回あれば十分
- 強い表現・印象的な言い回しを多用しない。多用するとAIらしさが出る
避けるべきパターン（AIらしい文章の典型）
太字・強調の乱用
- NG: 段落ごとにボールドが入る、「これが最も重要だ」「ここが核心だ」
- OK: 本当に目を止めてほしい箇所だけ。記事全体で数か所
冒頭の大仰な宣言
- NG: 「これが今日最も考えるべき問いだ。」「ここが設計の核心だ。」
- OK: 普通に事実を述べる
「つまり」「すなわち」「換言すると」の多用
- NG: 段落の締めに毎回まとめを入れる
- OK: 本当に要約が必要な場面だけ
箇条書きへの過剰依存
- NG: 文章で書けるものまですべてリスト化する
- OK: 並列関係にあるものだけリスト化する
平行構造の繰り返し
- NG: 同じ長さ・同じ文末の文が連続する（「〇〇する。△△する。□□する。」）
- OK: 文の長さや構造を自然に変える
最後の「まとめ」的な一言
- NG: セクションの末尾に「これが〜の本当の意味だ。」と締める
- OK: 次のセクションへ自然につなぐか、何も言わず終わる
強調副詞の多用
「非常に」「まさに」「絶対に」「最も」など。使うなら記事全体で1〜2回まで。
文章のトーン
記事によって合うトーンが異なる。無理に統一しない。
- 実装・ツール解説 → 淡々とした説明調
- 比較・選定 → 自分が調べているときの視点で書く（Supabase記事のように）
- 思想・設計論 → 少し距離を置いた考察調
タイトルの作り方
タイトルは記事の内容・価値・対象読者が伝わるように作る。以下のパターンを参考に。
| パターン | 例 |
|---|---|
| ゴール＋手段 | “エージェントを長く自律動作させるためのコンテキスト設計” |
| 問題＋解消 | “Claude と Codex のマルチエージェント引き継ぎ問題と解消パターン” |
| 疑問形 | “なぜフロントエンドに Vercel を選ぶのか” |
| 対象者＋ツール名 | “AI コーディング向けの Python フォーマッター Black” |
| 動詞句（何をするか） | “OpenAPI で API の仕様とドキュメントを同期させる” |
| 比較 | “Supabase vs Railway vs Neon バックエンド選定 (2026年版)” |
避けるパターン:
〇〇とは何かだけで止めない。用途・対象・文脈を加える──は禁止ではないが、使いすぎない。タイトルの主語が完結していれば──で足さない〇〇から△△まで解説/〇〇まで体系的に解説は使わない（subtitle も同様）
構成パターン
記事ごとに合う構成を選ぶ。毎回同じパターンにしない。
パターン A: 結論先行型
仕組みやツールの解説に向く。
導入（問題提起）
## 結論を先に
## 各セクション
## まとめ（表）
## 参考
パターン B: 調査ログ型
比較・選定・調べてみた系の記事に向く。Supabase vs Railway 記事がこの例。
導入（自分のユースケースや背景）
## 軸の整理 or 前提
## サービスA
## サービスB
## 比較・まとめ
## 参考
パターン C: 問題分解型
原因と対処を掘り下げる記事に向く。
導入（現象・問題）
## なぜ起きるか
## 構造の整理
## 対処パターン or 解決策
## まとめ
パターン D: 自由形式
上記に収まらない場合は無理に型に合わせない。読んで自然に流れる構成にする。
やってはいけないこと
_config.ymlを変更しない（サイト全体に影響する）_site/以下のファイルを直接編集しない（ビルド成果物）- 既存記事のフロントマターの
ref値を変更しない（日英リンクが壊れる） - 画像なしで
banner:を設定しない（表示が崩れる） - コミットは実行しない。作業完了後にコミットメッセージの案を提示すること
ローカル確認
# Docker で起動（推奨）
docker compose up
# ブラウザで確認
# http://localhost:4000
コミット規則
コミットはユーザーが実行する。作業完了後に以下の形式で案を提示すること。
add: 新規記事を追加したとき
fix: 記事内容の修正
update: 既存記事のアップデート
refactor: テンプレートや構造の変更（記事内容は変えない）