開発環境構築ガイド

このドキュメントに従えば、ローカル開発環境をゼロからセットアップできる。

1. 前提条件

2. リポジトリのクローンと依存インストール

リポジトリは private のため、オーナー (t-saitoh-bizlp) から Collaborator 招待を受ける必要がある。

招待を承諾したら SSH でクローンする:

git clone [email protected]:t-saitoh-bizlp/bizlp-gas-accounting.git
cd bizlp-gas-accounting
npm install

npm install で以下がインストールされる:

3. clasp のセットアップ

clasp は GAS プロジェクトをローカルから操作する CLI ツール。

3.1 インストール

npm install -g @google/clasp

動作確認:

clasp --version   # 3.x を確認

3.2 認証

clasp login --creds creds.json

• creds.json は Google Cloud Console で発行した OAuth クライアント ID (デスクトップアプリ) のファイル。リポジトリ管理者から受け取る
• creds.json は .gitignore で除外済み。リポジトリにコミットしない
• 認証が切れたら (invalid_grant / Skipping push.) 同じコマンドで再認証

3.3 環境別の clasp 設定

GAS プロジェクトは本番 (prod) と開発 (dev) に分離されている。

.clasp.dev.json   ← 開発用 scriptId (リポジトリ管理)
.clasp.prod.json  ← 本番用 scriptId (リポジトリ管理)
.clasp.json       ← 実際に clasp が参照するファイル (git 除外)

clasp-switch.sh で切り替える:

npm run switch:dev    # .clasp.dev.json → .clasp.json
npm run switch:prod   # .clasp.prod.json → .clasp.json
npm run status        # 現在どちらの環境か確認

3.4 GAS スクリプトプロパティ

各 GAS プロジェクトのスクリプトプロパティに以下を設定する (GAS エディタ → プロジェクトの設定):

4. npm scripts 一覧

デプロイ

ドキュメント

5. 開発フロー

git pull origin main → ブランチ作成 → コード修正 → clasp push (dev) → GAS で動作確認 → git commit → git push → PR → main マージ

動作未確認のコードを GitHub に push しない。

作業着手時の同期ルール

複数ワークスペース（§8）で並行作業するため、作業着手時は必ず git pull origin main --no-rebase で最新を取り込んでからブランチを切る。以下に該当する作業は特に重要:

• PR 作成 / commit を伴う変更
• 共有ファイル (CLAUDE.md, docs/_config.json, docs/_internal/TODO_future.md, docs/_internal/changelog.md, docs/dev/*.md, docs/_internal/research_questions.md, docs/_internal/research_prompts/) の編集
• メイン側で実装完了の通知を受けた後のドキュメント反映

同期を怠ると、並行作業で同じ ID の案件が重複起票される / 同じファイルが二重作成される 事故が発生する（例: 2026-04-20 に MAS-214 dev 仕様書が両ワークスペースで同時作成された事案）。

Claude Code のメモリ運用

~/.claude/projects/.../memory/ に feedback_auto_pull_main.md を配置しておくと、Claude Code が作業依頼を受けた際に 明示指示なしで自動 pull する。手動で「pull して」と毎回指示する負荷を軽減できる。

詳しいブランチ命名規則・デプロイフローは CLAUDE.md を参照。

6. CI/CD

GitHub Actions (deploy.yml) が main / dev ブランチへの push をトリガーに自動デプロイする。

• docs/** と *.md の変更はデプロイ対象外
• main へのデプロイ時は mas/900_test/ ディレクトリが自動削除される
• CI で使用する Secrets:
  • CLASPRC_JSON — clasp 認証情報
  • CLASP_SCRIPT_ID_PROD / CLASP_SCRIPT_ID_DEV — 各環境の scriptId
  • CLASP_DEPLOYMENT_ID_PROD / CLASP_DEPLOYMENT_ID_DEV — Web App のデプロイメント ID (任意)

7. AI ツール

本プロジェクトでは以下の AI ツールを開発に活用している。

7.1 Claude Code (CLI)

コード実装・リファクタリング・PR 作成などのメイン開発に使用する。

• CLAUDE.md にコーディング規約・ブランチ運用・テスト方針を定義し、Claude Code がそれに従って開発を行う
• MCP サーバー (Google Sheets) を接続してスプレッドシートの直接操作も可能

7.2 Roo Code (VS Code 拡張) — ドキュメント QA 向け

ドキュメントのリンク切れ・パス不整合・旧ファイル名残存を機械的に検出するために使用する。

精度・安全性設定

Custom Instructions

以下を Roo Code の Custom Instructions に設定する:

あなたは厳格で几帳面な『技術ドキュメントの品質管理（QA）エンジニア』です。
創造性や推測は一切不要です。提供された『正となるディレクトリ構成』と
『ドキュメントの内容』を機械的に照合し、1文字のパスのズレ、拡張子の間違い、
旧ファイル名の残存を容赦なく指摘してください。
指示された出力フォーマット（Markdownテーブル）を厳格に守り、
余計な挨拶や感想は出力しないでください。

Gemini Deep Research との連携方式

Roo Code は標準 Gemini API (generateContent) 経由のため、Gemini の Deep Research 機能（自律的な多段調査）を直接呼び出すことはできない（Deep Research は別エンドポイント Interactions API で、かつエンタープライズ allowlist 招待制）。

法制度・税務など外部調査が必要な論点は以下の 2 段階方式 で運用する:

1. docs/_internal/research_prompts/RQ-NNN_meta_prompt.md を Gemini Pro に投入 → Deep Research 用プロンプトを設計させる
2. 設計されたプロンプトを RQ-NNN_prompt.md として保存
3. Gemini Advanced（gemini.google.com） の Deep Research に投入
4. 結果を RQ-NNN_result.md として保存し、関連 dev_*.md の「人間が検討すべき事項」に反映

運用例は docs/_internal/research_prompts/README.md 参照（MAS-299 / MAS-304 / MAS-305 が稼働中）。

8. VS Code ワークスペース構成

本プロジェクトでは 2 つの VS Code ワークスペース を用途別に使い分ける。

• コード開発用ワークスペースでは clasp によるデプロイやコード変更を行う
• ドキュメント更新用ワークスペースではドキュメントの執筆・整合性チェックに専念する。コード変更は行わない
• ドキュメント更新用では Claude Code による執筆・構成作業と、Roo Code (Gemini) によるドキュメント QA (§7.2) の両方を活用する

並行作業時の競合事故パターンと対策

2 つのワークスペースで同時に Claude Code を走らせると、以下のような事故が発生する:

詳細な担当マトリクスは CLAUDE.md の「ファイル担当マトリクス」参照。

VS Code 推奨拡張機能