document-writer

ターゲットプロジェクトの技術ドキュメントを $ARGUMENTS に記述または更新します。

前提条件

<skill-dir> で始まるパスは、このスキルのベースディレクトリからの相対パスです。スキルの読み込み時に通知される、該当する実際のパスに置き換えてください。これは環境変数ではありません。

1. $ARGUMENTS が空の場合は、次の内容を報告します：Error: Please provide the target path and the documentation task (for example: './docs/api.md update the payment API docs' or './src/utils.ts add JSDoc for the public helpers').
2. 下書きを作成する前に、<skill-dir>/references/WORKFLOW.md、<skill-dir>/references/DOCUMENT_TYPES.md、<skill-dir>/references/VERIFICATION_CHECKLIST.md を読みます。
3. 依頼が中国語の場合、出力ファイルが中国語の場合、またはユーザーが中国語への推敲や書き換えを希望している場合は、<skill-dir>/references/CHINESE_TECH_WRITING.md も読みます。

実行フロー

1. タスクを分類する

執筆前に、最も近いドキュメントの種類を判断します。

• README.md または概要ドキュメント
• API リファレンスまたはエンドポイントのドキュメント
• アーキテクチャまたは設計の説明
• ユーザーガイド、運用ガイド、トラブルシューティング、FAQ
• CONTRIBUTING、メンテナンス、移行、リリースノート
• JSDoc、docstring、コードコメント

依頼されたファイル、ターゲットパス、ユーザーの依頼から種類を推測します。複数のドキュメントの種類によって出力が大きく異なる場合に限り、質問してください。

2. コードベースから根拠を集める

実際のプロジェクトファイルを信頼できる情報源として使用します。

1. 既存のドキュメントを先に読み、プロジェクトの用語を維持し、古くなった誤りの重複を避けます。
2. ディレクトリ構成、エントリーポイント、設定、公開インターフェース、サンプル、テストを調べます。
3. 動作を説明する場合は、ファイル名だけでなく、入力から出力まで重要なフローを追跡します。
4. API またはアーキテクチャのドキュメントでは、ルート、設定キー、環境変数、デフォルト値をコードと照合します。
5. JSDoc またはコメントを書く場合は、執筆前に対象シンボルの実装を読みます。

3. 言語、対象読者、出力場所を決める

1. ユーザーが指定した言語、または周囲のドキュメントで既に使われている言語に合わせます。
2. 中国語への書き換えタスクの場合は、1 行ずつ翻訳するのではなく、中国語の執筆リファレンスに従います。
3. 明示的に指定されたファイルを、その場で更新することを優先します。
4. ファイルが具体的に指定されていない場合は、慣例的な場所を使用します。
   • README.md、CONTRIBUTING.md、MIGRATION.md はリポジトリのルート
   • ユーザー向け、API、アーキテクチャのドキュメントは docs/
   • JSDoc またはコードコメントはソースファイル
5. リポジトリを調べても場所が曖昧な場合は、要点を絞って質問します。

4. 適切な構成で下書きを作成する

1. DOCUMENT_TYPES.md の該当するテンプレートと必須セクションを適用します。
2. 実際の範囲に合わせて詳細度を調整します。
   • 小規模なユーティリティまたはモジュール：セクションを絞った簡潔なドキュメント
   • 複数コンポーネントにまたがるフローまたは公開 API：例と失敗時のケースを含む完全な構成
3. ディレクトリツリーを機械的になぞるのではなく、読者のタスク、公開インターフェース、またはデータフローを中心に構成します。
4. 複数のコンポーネントを扱うアーキテクチャドキュメントには、リポジトリで別の形式が明示的に使われている場合を除き、Mermaid 図を含めます。

5. 検証に耐えられる内容を作成する

1. コマンド、コードスニペット、関数シグネチャ、環境変数、設定値は、実際のファイルに基づいて記述します。
2. 無理に翻訳するより明確な場合は、業界標準の英語用語を維持します。
3. 中国語のドキュメントでは、逐語訳ではなく自然な中国語表現を優先します。
4. リポジトリからは確認できず、完全性のために必要な事実に限り、TODO: を使用します。
5. コメントや JSDoc では、公開契約、副作用、不変条件、エラー、または自明でない動作を説明します。コードの内容を言い換えるだけの定型コメントは追加しません。

6. 引き渡し前に確認する

VERIFICATION_CHECKLIST.md に沿って確認し、以下を満たしていることを確認します。

• 重要な主張がすべて、コード、設定、テスト、または既存のメンテナンス対象ドキュメントによって裏付けられている
• 例やコマンドがプロジェクトの構成と一致している
• リンクとファイルパスが存在している
• シークレット、トークン、非公開のエンドポイント、または内部限定のメモが漏れていない
• 中国語の出力が、該当する場合、中国語の文章作成ガイドに従っている

ルール

• API、CLI フラグ、設定のデフォルト値、パフォーマンス数値、実装の詳細を捏造しないでください。
• コードと一致するか確認せずに、古いドキュメントの文言をそのままコピーしないでください。
• 英語表記が一般的な技術用語を、不自然な中国語に翻訳しないでください。
• 簡潔で、率直かつプロフェッショナルなトーンを保ってください。
• ドキュメントの成果物のみを出力してください。ユーザーが明示的に求めない限り、余計な会話上の説明は避けてください。