docs-update

ドキュメント更新ワークフロー

SSOT を考慮したドキュメント変更のワークフローです。

前提条件

• ブランチ、コミット、PR のワークフローでは、git-workflow Skill を使用してください。
• ドキュメントを編集する前に、SSOT の構造を把握してください。

SSOT の把握

重要：ドキュメントを編集する前に、そのファイルが SSOT か、SSOT を参照しているかを確認してください。

SSOT の場所

カテゴリ	SSOT の場所	説明
エージェントの動作	AGENTS.md	すべてのエージェントのエントリーポイント
エージェント指示の設計	docs/ai/design.md	Command／Skill／Rule のアーキテクチャ
ラベルの定義	docs/guidelines/task-classification.md	すべてのラベルの種類と意味
ラベル → Skill のマッピング	.claude/skills/label-context-mapping/	運用上のルーティング
コーディング規約	docs/guidelines/coding-conventions.md	コードスタイルのルール
セキュリティルール	docs/guidelines/security.md	セキュリティ要件
テスト標準	docs/guidelines/testing.md	テスト要件
ワークフロー	docs/guidelines/workflow.md	開発ワークフロー

SSOT のルール

1. SSOT ファイルを編集する場合：他のファイルが参照しているため、慎重に更新してください
2. SSOT 以外のファイルを編集する場合：情報を重複させず、SSOT を参照していることを確認してください
3. 情報が矛盾する場合：SSOT を正とし、参照元のファイルを更新してください

対象ファイル

パス	種類	説明
AGENTS.md	SSOT	エージェントの動作のエントリーポイント
ARCHITECTURE.md	SSOT	システムアーキテクチャ
docs/guidelines/	SSOT	プロジェクトのガイドラインと標準
docs/design/	参照	設計ドキュメント
docs/chains/	参照	チェーン固有のドキュメント
docs/ai/task-contexts/	コンテキスト	タスク固有の手順
internal/AGENTS.md	スコープ付き SSOT	内部パッケージのガイドライン
pkg/AGENTS.md	スコープ付き SSOT	公開パッケージのガイドライン

ドキュメントの階層

AGENTS.md (entry point)
    │
    ├─ docs/ai/design.md (instruction system design)
    │
    ├─ docs/guidelines/ (guidelines and standards)
    │   ├─ task-classification.md (label definitions, SSOT)
    │   ├─ coding-conventions.md
    │   ├─ security.md
    │   ├─ testing.md
    │   ├─ workflow.md
    │   ├─ architecture.md
    │   ├─ code-generation.md
    │   └─ ...
    │
    └─ docs/ai/task-contexts/ (task-specific context)
        ├─ bug-fix.md, feature-add.md, etc.
        └─ chains/ (chain-specific)

ワークフロー

1. ドキュメントの種類を特定する

編集する前に、次の点を確認してください。

• このファイルは SSOT ですか？
• このファイルは SSOT を参照していますか？
• 影響を受ける可能性がある他のファイルはありますか？

2. 重複した情報がないか確認する

追加する情報がすでに別の場所にある場合：

• SSOT の場所を確認する
• 情報を重複させず、参照を追加する

3. 変更を加える

Markdown のスタイルガイドラインに従ってください。

• ATX スタイルの見出し（#、##、###）を使用する
• セクション間には空行を 1 行入れる
• 言語指定子を付けたコードブロックを使用する
• 構造化データには表を使用する
• ドキュメント内のリンクには相対パスを使用する

4. 相互参照を確認する

変更後、次の点を確認してください。

• リンクが正しく機能する
• SSOT への参照が正確である
• 情報が重複していない
• 書式に一貫性がある

Markdown のスタイル

見出し

# Top Level (document title)

## Section

### Subsection

コードブロック

言語を必ず指定してください。

```go
func example() {}
```

make go-lint

### Tables

Use tables for structured data:

```markdown
| Column 1 | Column 2 |
|----------|----------|
| Value 1  | Value 2  |

リンク

• 相対リンクを使用する：[link](../path/to/file.md)
• ファイルの移動後にリンクが機能することを確認する
• 名前を変更した場合は相互参照を更新する

セルフレビューのチェックリスト

• 該当する場合、SSOT の場所を特定した
• 情報が重複していない
• 参照先が正しい SSOT を指している
• Markdown が正しく表示される
• リンクが機能する
• 書式に一貫性がある
• 表の列が正しく揃っている

コミットと PR

コミットには git-workflow スキルを使用します。

• コミットタイプ：docs
• スコープ：省略可能（または対象領域：btc、eth、standards など）

例：docs(standards): update coding conventions for error handling

関連項目

• git-workflow - ブランチ、コミット、PR のワークフロー
• AGENTS.md - エージェントのエントリーポイント
• AI Agent Instruction Design - システム設計
• Task Classification - ラベルの SSOT