contributing

Cloudflare Docs へのコントリビューション

Cloudflare Docs リポジトリに変更を加える際は、このスキルだけを読み込んでください。このスキル自体に詳細は記載されておらず、作業に適したリファレンスを案内します。作業に合ったリファレンスを読み、それに従ってください。

慣例を推測しないでください。以下のリファレンスが、このリポジトリで期待されるコンテンツの記述方法、構成方法、検証方法の正式な情報源です。

正式なリファレンスとローカルのパターンが矛盾する場合は、正式なリファレンスが優先されます。特に、製品セクション名、フォルダー、順序についてはこのルールに従ってください。

基本ルール

以下は、すべての作業に適用されます。

• このリポジトリはオープンソースの公開リポジトリです。 Cloudflare の非公開情報、シークレット、認証情報、社内 URL、環境変数の値を、ページ、コード例、コミット、プルリクエスト、コメント、またはこのリポジトリ内のその他の場所に記載しないでください。公開しても安全かどうか少しでも疑わしい場合は、作業を中断してユーザーに確認してください。
• 最新の production からブランチを作成してください。 作業を始める前に、ユーザーから別のベースを指定されていない限り、最新の production コミットからブランチを作成してください（git fetch origin を実行してから origin/production をベースにブランチを作成します）。このリポジトリのデフォルトブランチは main ではなく production です。
• 自動でコミットやプッシュをしないでください。 ファイルを変更したら、コミットとプッシュを希望するかユーザーに確認してください。明示的な指示がない限り、git commit や git push を実行しないでください。

作業を始める前に：背景情報を集める

元の資料が乏しい場合や曖昧な場合は、執筆を始める前に作業を中断してユーザーに確認してください。必要なのは、書式が整っているだけでなく、内容が正確に書けるだけの情報です。不足している情報を尋ねてください。

• 正式な情報源 — PR、RFC、エンジニアリング仕様書、API スキーマ、既存のページ、または動作を確認できるプロダクトオーナー。技術的な主張を捏造しないでください。
• 製品と機能領域 — どの Cloudflare 製品か、またその製品のどこに変更が属するか。
• 読者と目的 — 誰が読むのか、また読者が何をしようとしているのか（使い始める、情報を調べる、手順に従う、概念を理解する）。
• 提供状況 — プランの提供状況（Free／Pro／Business／Enterprise）とライフサイクルのステータス（GA、Beta、Alpha）。
• 範囲 — 新しいページ、既存ページの編集、再構成、変更履歴のいずれか。

ユーザーから明確な仕様書や PR がすでに提供されている場合は、追加の質問をせずに作業を進めてください。

タスク一覧

自分のタスクを見つけ、記載されている参考資料を確認してください。パスは、.agents/ が付いているものを除き、このスキルディレクトリからの相対パスです。

タスク	確認する資料
ドキュメントページの作成または編集	references/writing-docs.md（執筆ワークフロー — まずここから）
pcx_content_type とページの形式を決める	references/content-types.md
データの提示方法と使用するコンポーネントを決める	references/choosing-components.md
ページの配置場所、リダイレクト、再利用を決める	references/information-architecture.md
執筆・書式ルールを確認する	.agents/references/style-guide.md（正式なガイド）および手順ごとの説明がある .agents/references/procedures.md
コンポーネントのプロパティと使用例を確認する	.agents/references/components.md
変更履歴のエントリを追加または編集する	references/changelog.md
ドキュメントをレビューする／PR に提案する	references/reviewing-docs.md

references/writing-docs.md の執筆ワークフローでは、これらの資料を組み合わせて、コンテキストの収集 → ページの配置場所の特定 → コンテンツタイプの選択 → スタイルガイドに沿った草稿の作成 → 各データに適したコンポーネントの選択 → 検証を行います。

完了前に検証する

コンテンツを変更した後は、必ず検証を実行してください。環境に応じてコマンドを選択してください。フルビルドはローカルでのみ実行できます。

pnpm run check              # Type-check: validates frontmatter schemas + Astro types
pnpm run build              # Full build: validates MDX parsing, image paths, internal links — LOCAL ONLY (times out in CI)
pnpm run format             # Auto-fix Prettier formatting on edited files

CI（CI=true）では、pnpm run build をスキップし、pnpm run check、pnpm run lint、pnpm run format:core:check のみを実行してください。

public/__redirects を変更した場合は、次も実行してください。

pnpm exec tsm bin/validate-redirects.ts

変更したファイルには必ず pnpm run format を実行してください。フォーマットされていないコンテンツがあると、CI は失敗します。