1. 導入: なぜチームで「書く」ことが重要なのか？
DevOpsやインフラの現場では、日々大量の技術情報や手順、設定ファイルが生まれます。これらの情報を「自分だけが知っている」状態にしてしまうと、それはそのままチームのボトルネックや属人化のリスクとなります。新たなメンバーのオンボーディングに時間がかかったり、障害発生時に担当者不在で復旧が遅れたり、といった経験はありませんか？
この記事では、DevOps・インフラエンジニアがチームとして効率的に、そして高品質に「書く」ための実践的なアプローチを紹介します。ここで言う「書く」とは、単にドキュメントを作成することだけでなく、IaC（Infrastructure as Code）のコードやスクリプト、Runbookの作成・更新など、チームで共有し、改善していく全ての情報資産の作成活動を指します。共同で「書く」文化を育むことで、知識の共有、品質の向上、そしてチーム全体の生産性向上を実現しましょう。
2. 基礎知識: 共同作業を支えるツールと概念
DevOps・インフラ領域における共同作業を円滑に進めるためには、いくつかの重要なツールと概念を理解しておく必要があります。
- バージョン管理システム（Git）:
コード、設定ファイル、ドキュメントなど、あらゆるテキストベースのファイルを履歴と共に管理するためのシステムです。誰が、いつ、どのような変更を行ったかを追跡でき、変更の衝突を解決したり、過去の状態に戻したりする機能を提供します。チームでの共同作業の基盤中の基盤となります。
- プルリクエスト（PR）/マージリクエスト（MR）:
Gitベースの開発フローにおいて、自分の変更をメインブランチ（例: main, develop）に取り込む前に、チームメンバーにレビューを依頼する仕組みです。これにより、コードの品質向上、知識共有、潜在的な問題の早期発見が可能になります。
- IaC（Infrastructure as Code）:
インフラの構築や設定をコードとして定義し、バージョン管理システムで管理するアプローチです。Terraform、Ansible、CloudFormationなどが代表的です。インフラもコードとして扱うため、Gitによる共同作業の恩恵を最大限に受けられます。
- ドキュメント管理ツール:
Confluence, Notion, Sphinx with Read the Docsなど、チームでドキュメントを共有・管理するためのツールです。Wiki形式で手軽に編集できるものから、コードベースでドキュメントを生成するものまで様々です。
参考本文にあった「履歴機能」はGitの強力なバージョン管理機能が、「共同編集」はPR/MRを通じたコードレビューと連携した共同作業が、現代のDevOps・インフラエンジニアにとっての核となります。
3. 実装/解決策: チームで効率的に「書く」ための実践ステップ
共同で「書く」文化を定着させるためには、段階的なアプローチと明確なガイドラインが有効です。
1.
オンボーディングとハンズオンで心理的ハードルを下げる
新しいメンバーやGitに不慣れなメンバーには、まずGitの基本操作（clone, branch, add, commit, push, pull）を体験してもらいましょう。特に「間違えても大丈夫」という安心感を与えることが重要です。
例えば、意図的にテスト環境のIaCファイルを変更してPRを作成し、その変更を取り消す（revert）流れをハンズオンで経験してもらうことで、Gitのセーフティネットを理解させます。
2.
既存資産の修正から始める
いきなり新しいIaCモジュールや大規模なドキュメント作成を依頼するのではなく、既存のファイルやドキュメントの小さな修正から始めてもらいましょう。例えば、既存のRunbookの誤字脱字修正、説明の加筆、古い情報の更新などです。これにより、心理的な抵抗感を減らし、ツールの操作に慣れることができます。
3.
新規作成はテンプレートと既存例を参考に
新しいIaCモジュールや手順書を作成してもらう際には、テンプレートの活用を促しましょう。また、「この前の〇〇のIaCファイルが参考になるよ」といった具体的な既存のコード例を提示することで、ゼロから考える負担を軽減できます。
作成されたら、まずはその貢献を感謝し、細かい指摘は後回しにして、まずは「書く」こと自体を奨励する姿勢が大切です。
4.
標準化とルール作り
チームで「書く」量が増えてきたら、以下のような標準化ルールを決めましょう。
- 命名規則: ファイル名、変数名、リソース名、ドキュメントタイトルなど。例: 議事録は「YYYYMMDD_会議名.md」、Terraformモジュールは「modules/サービス名/」など。
- ディレクトリ構造: IaCリポジトリやドキュメントリポジトリの標準的なディレクトリ構成を定義します。
- ドキュメント構成: ドキュメントの種類（設計書、手順書、障害報告書など）ごとに、含めるべき項目や見出しのレベルを定義します。
- コーディング規約: IaCやスクリプトにおいては、Prettierやterraform fmtなどの自動フォーマッターを導入し、コードスタイルの統一を図りましょう。
これらのルール自体もGitリポジトリや共有ドキュメントツールで管理し、変更履歴を残すようにしましょう。
4. サンプルプログラム: Gitを使った共同作業のミニマム例
ここでは、GitHub/GitLabなどのGitホスティングサービスを想定し、IaC（Terraformを想定）の変更をチームで共同作業する際の基本的なコマンドフローを示します。
1. チームのIaCリポジトリをローカルにクローンします
まだリポジトリがない場合は、管理者に確認してください。
git clone https://github.com/your-org/your-infra-repo.git
cd your-infra-repo
2. メインブランチ（例: main）が最新であることを確認します
git checkout main
git pull origin main
3. 新しい作業用のブランチを作成し、そのブランチに切り替えます
ブランチ名には、作業内容がわかるようにプレフィックス（feat/fix/docsなど）を付けましょう。
git checkout -b feat/add-new-s3-bucket
4. コードに変更を加えます
例として、Terraformのmain.tfファイルに新しいS3バケットリソースを追加します。
ここではエディタでファイルを編集する操作を想定しています。
vim main.tf
— main.tf の変更例 —
resource “aws_s3_bucket” “my_new_bucket” {
bucket = “my-awesome-team-unique-bucket-name”
acl = “private”
tags = {
Environment = “development”
Project = “my-awesome-app”
}
}
————————-
5. 変更内容をステージングエリアに追加します
git add main.tf
6. コミットメッセージを付けて変更をコミットします
コミットメッセージは「変更の要約」と「詳細」を記述すると良いでしょう。
例: feat: 新しいS3バケットを作成 (#123)
– 開発環境用のプライベートS3バケットを追加しました。
– 関連するJiraチケット: #123
git commit -m “feat: 新しいS3バケットを作成 for development environment”
7. 自分のブランチをリモートリポジトリにプッシュします
git push origin feat/add-new-s3-bucket
8. GitHub/GitLabのWeb UIにアクセスし、プッシュしたブランチからプルリクエスト（PR）を作成します
– PRのタイトルは変更内容が明確にわかるように記述します。
– PRの説明には、変更の目的、影響範囲、レビューしてほしい点などを詳しく書きます。
– 必要に応じてレビュワーをアサインします。
9. レビュワーからのフィードバックに基づいて、必要であればコードを修正し、再度プッシュします
修正後も上記と同様に git add, git commit, git push を行います。
git commit -m “fix: レビュー指摘事項に基づきバケット名を修正”
git push origin feat/add-new-s3-bucket
10. PRが承認され、メインブランチにマージされたら、ローカルのメインブランチを最新の状態に更新します
git checkout main
git pull origin main
11. 作業ブランチは不要になったら削除します（ローカルとリモート両方）
git branch -d feat/add-new-s3-bucket
git push origin –delete feat/add-new-s3-bucket
5. 応用・注意点: 現場で役立つ補足情報と落とし穴
チームで「書く」文化を育てる上で、さらに考慮すべき点や陥りがちな落とし穴について解説します。
-
建設的なレビュー文化の醸成
コードレビューやドキュメントレビューは、単なる間違い探しではなく、知識共有とスキルアップの貴重な機会です。指摘する際は、改善提案を具体的に示し、ポジティブな言葉遣いを心がけましょう。また、良い点や貢献にも「いいね」や感謝のコメントを積極的に送り、相手のモチベーションを高めることが重要です。
-
自動化とCI/CD連携
IaCやスクリプトの場合、PRが作成された際に自動的にLinterやフォーマッター（例: `terraform fmt –check`）を実行したり、IaC Plan（Terraform Planなど）の結果を表示したりするCI/CDパイプラインを構築しましょう。これにより、手動での確認の手間を省き、品質を均一化できます。ドキュメントも変更時に自動でテスト・デプロイされると理想的です。
-
ドキュメントの鮮度維持
ドキュメントは「書く」だけでなく、「更新し続ける」ことが重要です。システムやインフラが変更された際は、関連するドキュメントも同時に更新することをチームのルールとしましょう。コードとドキュメントの乖離は、不信感を生み、最終的には誰もドキュメントを読まなくなってしまいます。
-
ツールの選定と柔軟性
チームの規模、文化、要件に合わせて適切なツールを選定しましょう。また、ルールは一度決めたら終わりではなく、チームの成長や変化に合わせて柔軟に見直し、改善していく姿勢が大切です。過度に厳格なルールは、かえって「書く」ことへの抵抗感を生む可能性があります。
-
心理的なハードルを常に意識する
特に新しいメンバーや共同作業に不慣れな人にとっては、「間違えたらどうしよう」「完璧に書かなければ」というプレッシャーを感じやすいものです。「まずは完璧でなくても良いから、プッシュしてみよう」「Gitには履歴があるからいつでも元に戻せる」といったメッセージを繰り返し伝え、心理的な安全性を確保することが、活発な共同作業への第一歩となります。
チームで「書く」文化を育むことは、一朝一夕にはいきません。しかし、地道な努力と適切な仕組み作りによって、チームの知識ベースは着実に成長し、DevOps・インフラ領域の盤石な基盤となるでしょう。
コメント