Inner Source を作ろう by Coding Agent

# 背景

`Inner Source` を知ったのがかれこれ 6 年ぐらい前

これだ！と思ったけれど、同志を作れず、無為に過ごしてたら・・

親会社で去年から活動が進みだした。

そう、負けてられないよねって思ったので、アプローチと行動を増やすことにした

今回の記事は、GitHub に Repository を作成した直後に、Copilot Coding Agentに Inner Source 用の環境作成を依頼するための Issue の sample

# sample issue driven by Copilot

これをちょっとシンプルにして、社内で作る予定

まぁ、おそらく問題は起きるので、CI の修正は必要だとは思うけど、色々面倒なことをサクッとやってくれるのは本当にありがたい

<blockquote>
# Inner Source Repository 環境整備設計書

## 概要

社内横断での活用を目的とした Inner Source Repository の環境整備を行う。多言語対応のスクリプト・ライブラリ・ツール類を集約し、チーム間での知識・コード共有を促進する基盤を構築する。

## 目標

1. **多様な資産の共有**: Python, JavaScript, PowerShell, C# 等のスクリプト、ブラウザ拡張機能、Bookmarklets 等を含む包括的な共有環境
2. **貢献しやすい環境**: サンプルコードとテストを含む、参加しやすい仕組みの提供
3. **品質保証**: 自動化された CI/CD とコードレビュープロセス
4. **開発体験向上**: VSCode 統合と GitHub Copilot 活用による効率的な開発環境
5. **知識の蓄積**: 各種ツール・スクリプトの開発ノウハウの共有と継承

## アーキテクチャ設計

### ディレクトリ構造（概要）

```
/
├── .github/                    # GitHub設定
│   ├── ISSUE_TEMPLATE/         # Issue テンプレート
│   ├── workflows/              # GitHub Actions
│   └── instructions/           # GitHub Copilot 指示書
├── .vscode/                    # VSCode設定
├── src/                        # メインソースコード
│   ├── python/                 # Python プロジェクト
│   ├── javascript/             # JavaScript プロジェクト
│   ├── powershell/             # PowerShell モジュール
│   ├── csharp/                 # C# プロジェクト
│   ├── browser-extensions/     # ブラウザ拡張機能
│   └── bookmarklets/           # ブックマークレット
├── docs/                       # ドキュメント
├── templates/                  # プロジェクトテンプレート
└── tests/                      # 統合テスト
```

### src/ 配下の構成指針

各言語・技術カテゴリ配下には、実際に動作するサンプルプロジェクトを配置する：

- **言語別フォルダ**: 各言語での典型的な処理パターンのサンプル
- **browser-extensions/**: Edge/Chrome 拡張のサンプルプロジェクト
- **bookmarklets/**: 業務効率化・開発支援用ブックマークレット

利用者はこれらのサンプルを参考に、実装パターンや構成を理解できる。

### 技術スタック

- **バージョン管理**: Git + GitHub
- **CI/CD**: GitHub Actions
- **エディタ**: VSCode (推奨)
- **AI 支援**: GitHub Copilot
- **品質管理**: 各言語の標準的なリンター・フォーマッター

## 実装計画

### Phase 1: 基盤整備

- [ ] **リポジトリ全体の GitHub 設定**
  - [ ] Issue/PR テンプレート（共通）
  - [ ] CODEOWNERS ファイル
  - [ ] コミュニティガイドライン（CONTRIBUTING.md, CODE_OF_CONDUCT.md）
  - [ ] GitHub Copilot 指示書（共通開発標準）
- [ ] **VSCode 設定ファイル群の作成**
  - [ ] マルチプロジェクト対応のワークスペース設定
  - [ ] 言語別の推奨拡張機能
  - [ ] 統合デバッグ設定
- [ ] **モノレポ対応 GitHub Actions（実践重視）**
  - [ ] パスフィルタによる効率的な CI/CD（`on.push.paths` / `on.pull_request.paths` 設定）
  - [ ] 変更検出アクション（`dorny/paths-filter` 等）の活用
  - [ ] 条件付き実行（`if` ステートメントによるスキップ制御）
  - [ ] セキュリティスキャン（全プロジェクト共通）
  - [ ] 依存関係の脆弱性チェック
  - [ ] **Actions 設定のベストプラクティス集**
    - [ ] 適切な権限設定（`permissions` ブロック）
    - [ ] シークレット管理のガイドライン
    - [ ] キャッシュ戦略（`actions/cache` の効果的活用）
    - [ ] 並列実行とジョブ依存関係の設計
    - [ ] 失敗時の通知・デバッグ手順

### Phase 2: サンプルコード作成

- [ ] **Python サンプルプロジェクト**
  - [ ] プロジェクト固有の .github/workflows/（よくある落とし穴対策済み）
  - [ ] pytest + coverage 設定（Actions でのレポート出力含む）
  - [ ] requirements.txt / pyproject.toml（依存関係の固定化）
  - [ ] README.md（使用方法・設定方法・トラブルシューティング）
  - [ ] **Actions 設定例**
    - [ ] Python バージョンマトリックステスト
    - [ ] 依存関係キャッシュ設定
    - [ ] テスト結果の可視化（test-reporter 等）
- [ ] **JavaScript サンプルプロジェクト**
  - [ ] Node.js + npm/yarn 設定（package-lock.json 管理含む）
  - [ ] Jest テスト環境（Actions での並列実行設定）
  - [ ] ESLint + Prettier 設定（Actions での自動修正オプション）
  - [ ] package.json（スクリプト・依存関係）
  - [ ] **Actions でよくある問題の対策**
    - [ ] Node.js バージョン管理（.nvmrc ファイル活用）
    - [ ] npm/yarn キャッシュ設定
    - [ ] ESLint エラー時の適切な終了コード
- [ ] **PowerShell サンプルスクリプト**
  - [ ] Pester テストフレームワーク
  - [ ] PSScriptAnalyzer 設定
  - [ ] モジュールマニフェスト (.psd1)
- [ ] **C# サンプルプロジェクト**
  - [ ] .NET プロジェクト構成（Actions での複数フレームワーク対応）
  - [ ] xUnit テストプロジェクト（テスト結果の Actions 連携）
  - [ ] EditorConfig 設定
  - [ ] **Actions 特有の設定**
    - [ ] .NET バージョンマトリックス
    - [ ] NuGet キャッシュ設定
    - [ ] コードカバレッジレポート（Coverlet + ReportGenerator）
- [ ] **ブラウザ拡張機能サンプル**
  - [ ] Manifest V3 対応
  - [ ] TypeScript + webpack 設定
  - [ ] クロスブラウザテスト環境
- [ ] **Bookmarklet サンプル集**
  - [ ] テンプレート・ベストプラクティス
  - [ ] セキュリティガイドライン
  - [ ] 配布・インストール方法

### Phase 3: 共有機能強化

- [ ] プロジェクトテンプレート作成
- [ ] コントリビューションガイドライン
- [ ] 自動化ワークフローの拡張

## 成功指標

1. **採用率**: 月次の新規コントリビューション数
2. **品質**: PR でのレビュー指摘事項の減少
3. **効率**: 新規プロジェクト立ち上げ時間の短縮
4. **満足度**: 開発者フィードバックによる改善点の特定

## GitHub Actions 実装時の注意点とベストプラクティス

### よくある問題と対策

#### 1. パス変更検出の設定ミス

```yaml
# ❌ 間違い: パスの書き方が曖昧
on:
  push:
    paths:
      - src/python/*

# ✅ 正解: 適切なパターン指定
on:
  push:
    paths:
      - 'src/python/**'
      - '.github/workflows/python-*.yml'
```

#### 2. キャッシュキーの設計不良

```yaml
# ❌ 間違い: キャッシュが効かない
- uses: actions/cache@v3
  with:
    key: node-modules

# ✅ 正解: 依存関係ファイルのハッシュを含める
- uses: actions/cache@v3
  with:
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
```

#### 3. 権限設定の不備

```yaml
# ❌ 間違い: 必要以上の権限
permissions: write-all

# ✅ 正解: 最小権限の原則
permissions:
  contents: read
  issues: write
  pull-requests: write
```

#### 4. 条件分岐の誤用

```yaml
# ❌ 間違い: 常に実行される
if: github.event_name == 'push'

# ✅ 正解: 適切な条件設定
if: github.event_name == 'push' && !contains(github.event.head_commit.message, '[skip ci]')
```

### 推奨する Actions 構成パターン

#### モノレポ用の変更検出パターン

```yaml
name: Detect Changes
on: [push, pull_request]
jobs:
  changes:
    runs-on: ubuntu-latest
    outputs:
      python: ${{ steps.changes.outputs.python }}
      javascript: ${{ steps.changes.outputs.javascript }}
      csharp: ${{ steps.changes.outputs.csharp }}
    steps:
      - uses: actions/checkout@v3
      - uses: dorny/paths-filter@v2
        id: changes
        with:
          filters: |
            python:
              - 'src/python/**'
            javascript:
              - 'src/javascript/**'
            csharp:
              - 'src/csharp/**'
```

#### 言語別テストジョブのパターン

```yaml
  test-python:
    needs: changes
    if: ${{ needs.changes.outputs.python == 'true' }}
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [3.8, 3.9, '3.10', '3.11']
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: ${{ matrix.python-version }}
      - uses: actions/cache@v3
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt') }}
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt -r requirements-dev.txt
      - name: Run tests
        run: |
          python -m pytest --cov --cov-report=xml
      - name: Upload coverage
        uses: codecov/codecov-action@v3
```

### デバッグとトラブルシューティング

#### 1. Actions の実行ログの効果的な活用
- [ ] デバッグモード（`ACTIONS_STEP_DEBUG: true`）の設定方法
- [ ] 詳細ログ（`ACTIONS_RUNNER_DEBUG: true`）の活用
- [ ] 失敗時のアーティファクト保存設定

#### 2. ローカルでの Actions テスト
- [ ] `act` ツールを使用したローカル実行
- [ ] Docker での環境再現
- [ ] シェルスクリプトでの事前検証

#### 3. セキュリティベストプラクティス
- [ ] `GITHUB_TOKEN` の適切な使用
- [ ] サードパーティアクションのバージョン固定
- [ ] Dependabot によるアクション更新

### よくある落とし穴と解決策

#### パフォーマンス関連
- [ ] **不要な実行の回避**: `[skip ci]` コミットメッセージの活用
- [ ] **並列実行の最適化**: ジョブの依存関係を最小限に抑制
- [ ] **アーティファクトサイズの制限**: 不要なファイルの除外

#### エラーハンドリング
- [ ] **失敗時の継続実行**: `continue-on-error: true` の適切な使用
- [ ] **リトライ機構**: 外部依存での一時的失敗への対処
- [ ] **通知設定**: Slack/Teams への失敗通知の設定

#### メンテナンス性
- [ ] **コードの重複排除**: 再利用可能なコンポジットアクションの作成
- [ ] **バージョン管理**: Actions バージョンの定期更新
- [ ] **ドキュメント**: Actions の動作説明とトラブルシューティング手順

## リスク管理

- **セキュリティ**: secrets の適切な管理と scanning の実装
- **品質**: 自動テストの充実と review process の標準化
- **メンテナンス**: 定期的な依存関係更新とツールバージョンアップ

### .github ディレクトリの役割分担

Inner Source リポジトリでは、リポジトリ全体の運営と個別プロジェクトの管理で`.github`の役割が異なる：

#### ルートレベル `.github/` （リポジトリ全体）

- **Issue テンプレート**: 新規貢献、バグ報告、機能要求等の共通テンプレート
- **PR テンプレート**: 全言語共通のレビュー観点・チェックリスト
- **ワークフロー**: リポジトリ全体の品質管理（セキュリティスキャン、依存関係チェック等）
- **Copilot 指示書**: 開発標準、命名規則等の共通ガイドライン
- **コミュニティガイド**: CONTRIBUTING.md、CODE_OF_CONDUCT.md 等

#### プロジェクトレベル `.github/` （src/各言語配下）

- **言語固有ワークフロー**: テスト実行、ビルド、リリース等
- **プロジェクト固有テンプレート**: 技術特化した Issue/PR テンプレート
- **依存関係管理**: Dependabot 設定、セキュリティアップデート等

### モノレポ管理の考慮事項

#### GitHub Actions の設計

- **パスフィルタ**: 変更されたプロジェクトのみ実行する効率的なワークフロー
- **マトリックス戦略**: 複数言語・環境での並列テスト実行
- **共通アクション**: 再利用可能なカスタムアクションの活用

#### コードオーナーシップ

- **CODEOWNERS**: 言語・技術領域ごとの責任者設定
- **パス別レビュー**: 各プロジェクトの専門家による適切なレビュー体制

## モノレポ運営の課題と対策

### 技術的課題

- **ビルド時間の増大**: 変更範囲に応じた効率的な CI/CD 設計
- **依存関係の競合**: 言語・プロジェクト間での依存関係の管理
- **リポジトリサイズ**: 大容量ファイルの管理と Git LFS 活用

### 運営・管理の課題

- **権限管理**: プロジェクト別の書き込み権限とレビュー体制
- **リリース管理**: 個別プロジェクトの独立したリリースサイクル
- **通知管理**: 関係者のみに適切な通知を送る仕組み

### 解決策

- **モノレポツール**: Nx, Lerna, Rush 等の活用検討
- **明確な責任分界**: CODEOWNERS による所有権の明確化
- **自動化の推進**: 手動作業を最小限に抑える CI/CD 設計

### 追加で必要な環境整備要素

#### セキュリティ・ガバナンス

- [ ] **Secret Scanning**: API キー、パスワード等の機密情報検出
- [ ] **Dependency Review**: プルリクエスト時の依存関係チェック
- [ ] **Branch Protection Rules**: main ブランチの保護設定
- [ ] **Required Status Checks**: マージ前の必須チェック設定

#### ドキュメンテーション

- [ ] **アーキテクチャ決定記録 (ADR)**: 技術選択の背景・理由の記録
- [ ] **API ドキュメント**: 自動生成される開発者向けドキュメント
- [ ] **チュートリアル**: 新規参加者向けのステップバイステップガイド
- [ ] **トラブルシューティング**: よくある問題と解決方法

#### コミュニティ・ガバナンス

- [ ] **議論フォーラム**: GitHub Discussions の活用
- [ ] **定期ミーティング**: 月次の技術共有会・レビュー会
- [ ] **メンテナー定義**: 各プロジェクトの責任者・権限の明確化
- [ ] **ライセンス管理**: 使用ライブラリのライセンス互換性確認

#### 監視・メトリクス

- [ ] **使用状況分析**: ダウンロード数、スター数、フォーク数の追跡
- [ ] **コード品質メトリクス**: カバレッジ、複雑度、技術的負債の監視
- [ ] **セキュリティアラート**: 脆弱性の自動検出・通知
- [ ] **パフォーマンス監視**: CI/CD の実行時間、ビルド成功率

</blockquote>

# あとがき

Copilot 君と壁打ちして作ってもらったものなので、細かいところはちゃんとみてません。

参考にする際にはご注意を

今好きな言葉は、以下 :laughing: 

- プロダクトに完了はない、スプリントにのみ完了はある。