コードとドキュメントの紐付け

ソースファイルと開発Wiki（docs/）を @docs コメントで相互リンクする規約です。 コードを読む開発者がすぐに関連ドキュメントにたどり着けるようにすることを目的としています。

記法

ファイル冒頭（import 文より前）に @docs ブロックコメントを記載します。

TypeScript / JavaScript

/**
 * @docs
 * - SDK仕様: docs/docs/uzu_code/play-screen-sdk.md
 * - ブリッジ仕様: docs/docs/uzu_code/bridge.md
 */
import { something } from "./something";

Go

// @docs
// - 通知設定の追加手順: docs/docs/services/uzu/backend/operations/notification-settings.md

package usecase

Dart

// @docs
// - エミュレータ仕様: docs/docs/uzu_code/emulator.md
// - システム全体像: docs/docs/uzu_code/overview.md
import 'package:flutter/material.dart';

WARNING

Dart では ///（doc comment）ではなく //（通常コメント）を使用してください。/// を使うと dangling_library_doc_comments lint エラーになります。

YAML / Shell

# @docs
# - N+1問題とcollect_path: docs/docs/services/uzu/backend/graphql/n-plus-one.md

GraphQL スキーマ

# @docs
# - 観戦参加仕様: docs/docs/services/uzu/mobile/specs/spectator-join.md

WARNING

backend の *.resolvers.go には書かないでください。gqlgen は再生成時に resolver 以外の記述を黙って削除するため、コメントが消えます。resolver の仕様は対応する backend/internal/adapters/graph/schema/*.gql か、*_helper.go / usecase/ 側に書いてください。

ルール

ルール	説明
配置場所	ファイルの先頭（import 文や package 宣言より前）
パス形式	リポジトリルートからの相対パス
複数ドキュメント	関連するものをすべて列挙する
ラベル	日本語で簡潔にドキュメントの内容を示す

TIP

shebang（#!/usr/bin/env node 等）がある場合は、shebang の直後に記載してください。

運用フロー

コード変更時

1. コードを変更する
2. /docs コマンドを実行する
3. 変更ファイルの @docs コメントから関連ドキュメントが自動検出される
4. ドキュメントとコードに齟齬があれば更新が提案される

新しいファイルを作成した時

関連するドキュメントが docs/ にある場合は、@docs コメントを追加してください。

新しいドキュメントを作成した時

そのドキュメントが説明しているソースファイルに @docs コメントを追加してください。