npm package: @hosty-jp/vibe-coding-rules
Description: Vibe coding guardrails for Claude Code - security, quality, and operational safety rules
Author: Hosty
Latest version: 0.1.4

# @hosty-jp/vibe-coding-rules

社内の vibe coding で生成されるコードの**セキュリティ・品質・運用安定性**を担保するための Claude Code ガードレールです。

Google Apps Script、Slack、Notion、Google Workspace、Freee 等の外部サービス連携を安全に行うためのルール・エージェント・hooks を提供します。

## インストール

プロジェクトのルートディレクトリに移動してから実行してください。

```bash
cd ~/work/my-gas-project
npx @hosty-jp/vibe-coding-rules init
```

プロジェクトに以下が配置されます:

```
CLAUDE.md                              # Claude Code が参照するルール概要
.claude/
  rules/
    gas-security.md                    # GAS セキュリティルール
    gas-best-practices.md              # GAS ベストプラクティス
    external-services.md               # 外部サービス連携ルール
    code-quality.md                    # コード品質基準
    vibe-coding-guard.md               # Vibe coding ガードレール
  agents/
    security-reviewer.md               # セキュリティレビューエージェント
    code-reviewer.md                   # コード品質レビューエージェント
    vibe-code-validator.md             # 総合バリデーションエージェント
```

また、プロジェクトの `.claude/settings.json` に hooks が自動追加されます（`--skip-hooks` でスキップ可）。

## コマンド

### init

```bash
npx @hosty-jp/vibe-coding-rules init
```

プロジェクトにルール・エージェント・hooks を配置します。

| オプション | 説明 |
|-----------|------|
| `--force` | 既存ファイルを上書き |
| `--skip-hooks` | hooks の自動設定をスキップ |

### update

```bash
npx @hosty-jp/vibe-coding-rules update
```

ルールを最新版に更新します。既存ファイルは `.bak` としてバックアップされます。

### check

```bash
npx @hosty-jp/vibe-coding-rules check
```

プロジェクト内のコードを静的解析し、問題を検出します。

検出項目:

| 重要度 | 内容 |
|--------|------|
| **CRITICAL** | APIキー直書き、`eval()` 使用 |
| **HIGH** | ログへの機密情報出力、エラーハンドリング漏れ |
| **MEDIUM** | `UrlFetchApp` の宛先未確認、ファイルサイズ超過 |
| **LOW** | `console.log` の残存 |

CRITICAL が検出された場合、exit code 1 で終了します。

## ルール概要

### セキュリティ

- APIキー・トークンは `PropertiesService` / 環境変数で管理
- `eval()` / `new Function()` 禁止
- `UrlFetchApp.fetch()` はホワイトリスト方式
- ログに機密情報を出力しない
- OAuth スコープは必要最小限

### GAS ベストプラクティス

- トリガーの無限ループ防止
- 実行時間制限（6分）への対処パターン
- `LockService` による排他制御
- スプレッドシートのバッチ処理（`getValues` / `setValues`）
- API Quota の管理

### 外部サービス連携

Slack、Notion、Google Workspace、Freee 等の連携ルール:

- 認証情報の安全な管理
- API レート制限の遵守
- 必要最小限の権限（スコープ）
- テスト環境と本番環境の分離

### コード品質

- 1ファイル 300行以下、1関数 50行以下
- エラーハンドリング（try-catch）必須
- ハードコード値禁止
- イミュータビリティ（データの変更禁止）
- 早期リターンでネスト削減

## セキュリティレビュー

コード編集後、hooks が自動で security-reviewer エージェントの実行を促します。
Claude Code のチャット上で以下のように依頼してください。

### 依頼方法

```
security-reviewer エージェントで変更したコードをレビューして
```

または具体的にファイルを指定:

```
.claude/agents/security-reviewer.md のエージェントで Code.gs をセキュリティレビューして
```

### 自動化の流れ

```
コード編集 (Edit/Write)
     │
     ▼
PostToolUse hook（自動実行）
     │
     ├─ CRITICAL 検出 → ブロック（APIキー直書き、eval 等）
     │
     └─ 安全 → Claude に表示:
        「[vibe-guard] タスク完了前に security-reviewer エージェントを実行してください」
     │
     ▼
ユーザーまたは Claude が security-reviewer を実行
     │
     ▼
セッション終了 (Stop hook)
     │
     └─ 未レビューなら警告表示
```

hooks が設定されていれば、コード編集のたびに `[vibe-guard]` メッセージが表示されます。
Claude はこのメッセージを読み、タスク完了前に自動で security-reviewer を実行します。

### レビュー結果の見方

security-reviewer は以下の形式でレポートを出力します:

```
## セキュリティレビュー結果

### CRITICAL
- [ファイル名:行番号] 問題の説明

### HIGH
- [ファイル名:行番号] 問題の説明

### 判定: PASS / FAIL
```

**FAIL** の場合は指摘箇所を修正してから再度レビューを依頼してください。

## エージェント一覧

| エージェント | 役割 | 依頼例 |
|-------------|------|--------|
| `security-reviewer` | セキュリティレビュー | `security-reviewer エージェントでレビューして` |
| `code-reviewer` | コード品質レビュー | `code-reviewer エージェントでレビューして` |
| `vibe-code-validator` | 運用可能性の総合判定 | `vibe-code-validator エージェントで検証して` |

## Hooks

`init` 時に以下の hooks がプロジェクトの `.claude/settings.json` に追加されます:

| フック | タイミング | 内容 |
|--------|-----------|------|
| セキュリティチェック | ファイル編集後 | CRITICAL 検出でブロック + security-reviewer 実行を指示 |
| セッション監査 | セッション終了時 | 未レビュー警告 + 変更ファイルのシークレット検出 |

## バージョン管理

最新バージョンでない場合、`init` / `check` 実行時にセキュリティ警告が表示されます:

```
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃  SECURITY WARNING                                        ┃
┃                                                          ┃
┃  セキュリティルールが最新ではありません!                  ┃
┃  古いルールには未対応の脆弱性パターンが含まれる           ┃
┃  可能性があります。                                      ┃
┃                                                          ┃
┃  今すぐ更新:                                             ┃
┃  npx @hosty-jp/vibe-coding-rules@latest update            ┃
┃                                                          ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
```

## 動作環境

- Node.js 18 以上
- Windows / macOS 対応
- 外部依存なし