Confluenceは「墓場」ではない。開発の加速装置にするための階層構造と設計思想
エンジニア諸君。君たちのConfluenceは今、どんな状態だ？
「検索しても古い仕様書しか出てこない」「どこに会議メモがあるか分からない」「結局Slackのログを遡るのが一番早い」。もしそうなら、君たちのチームのベロシティはツールによって物理的に削り取られている。
Confluenceは単なるドキュメント置き場ではない。「チームの集合知をプロダクトの成長に直結させるための神経系」だ。今日は、カオスを秩序に変え、開発速度を劇的に高めるための「設計の極意」を伝授する。
—
1. 「検索」に頼らない構造：階層設計のベストプラクティス
多くのチームが失敗するのは、ディレクトリ構造を「組織図」に合わせてしまうことだ。組織は変わる。だが、プロダクトの文脈は永続する。
推奨する「プロジェクトベース」のツリー構造
部門別ではなく、「プロダクトのライフサイクル」を軸に階層を切る。
- `00_Dashboard` (チームのポータル。現在のスプリント目標、直近のデプロイ予定をここに集約)
- `01_Product_Requirements` (要件定義、PRD、ユーザーシナリオ)
- `02_Architecture_Design` (システム構成図、API設計、DBスキーマ設計)
- `03_Development_Log` (デイリースクラムのメモ、意思決定の経緯)
- `04_Retrospective` (KPT、ふりかえり結果)
- `99_Archive` (完了済みプロジェクト、古くなった仕様)
極意： 「00」「01」といった接頭辞をつけることで、脳の認知負荷を下げ、視覚的な並び順を固定せよ。
—
2. 開発スピードを加速させる「神」テクニック
隠れたキーボードショートカット
マウス操作は思考のコンテキストスイッチを発生させる。以下のキーは指に覚え込ませろ。
- `c` : ページ作成（Create）
- `e` : 編集（Edit）
- `g` + `d` : ダッシュボードへ移動
- `/` : マクロ挿入（これが最重要。`jira`, `code`, `status`を瞬時に呼び出せ）
入れなければ始まらないプラグイン
1. Gliffy / Draw.io: アーキテクチャ図はテキストではなく図解で。Confluenceとの親和性が最強。
2. Scroll Documents: ページ群を「バージョン管理」できる。リリース単位での仕様書管理には必須。
3. Refined: Confluenceを「Wiki」から「チーム専用ポータル」に昇華させるUIカスタマイズツール。
—
3. 実践：ドキュメントの「型」をYAMLで定義する
ドキュメントの粒度を揃えるために、「テンプレートのYAML化（マクロの構成案）」を推奨する。以下の設計思想をテンプレートに落とし込め。
意思決定ログの構成案（Template YAML）
document_template:
metadata:
author: “owner_name”
status: “draft/review/approved”
tags: [“architecture”, “decision-log”]
sections:
- title: “Context”
description: “なぜこの判断が必要か？背景となる課題。”
- title: “Proposed Solution”
description: “採用する技術選定とその理由。”
- title: “Alternative Options”
description: “検討したが採用しなかった案（ここが最も重要）”
- title: “Risk & Impact”
description: “影響範囲と懸念事項。”
これをConfluenceのテンプレート機能に「型」として登録しておけば、新メンバーでも迷わず「価値のあるドキュメント」が書けるようになる。
—
4. チームで守るべき「3つの鉄則」
1. 「情報はプル型で共有せよ」
Slackで投げっぱなしにするな。重要な決定事項はConfluenceの該当ページに書き込み、SlackにはそのURLを貼る。「検索すれば絶対にある」という信頼がチームの安心感を生む。
2. 「古いドキュメントは殺せ」
古い仕様書に`[OUTDATED]`タグを付け、ページ上部に警告マクロを貼る。ゴミを放置することは、未来の自分たちに対する負債だ。
3. 「ラベル管理は厳格に」
`#sprint-2023-q4` や `#api-v2` などのラベルを統一せよ。これで、数年後のエンジニアが「あの時、なぜこのAPIにしたんだっけ？」と検索した瞬間に、当時の文脈が全て再現される。
—
最後に：Confluenceはチームの「第二の脳」である
エンジニア諸君。君たちの書くドキュメントは、コードと同じくらい、いや、それ以上に価値がある。なぜなら、コードは「何が行われているか」を語るが、ドキュメントは「なぜそれが必要だったのか」を語るからだ。
この構造設計を今日から導入してほしい。最初は面倒かもしれないが、半年後、君たちのチームは「過去の経緯を調べる時間」を「新しい機能を創り出す時間」に変換できているはずだ。
さあ、エディタを開け。まずはポータルの整理からだ。