existing-repo

既存リポジトリのスキル

既存のコードベースで作業する際に、構成を分析し、慣例を尊重し、何も壊さずに適切なガードレールを整備します。

ソース： Husky | lint-staged | pre-commit | commitlint

---

基本原則

変更する前に理解する。 既存のリポジトリには慣例、パターン、履歴があります。あなたの役割は、それらを再構成するのではなく、その中で作業することです。

---

フェーズ 1：リポジトリの分析

既存のリポジトリに参加したら、必ず最初にこの分析を実行してください。

1.1 基本情報の検出

# Check git status
git remote -v 2>/dev/null
git branch -a 2>/dev/null
git log --oneline -5 2>/dev/null

# Check for existing configs
ls -la .* 2>/dev/null | head -20
ls *.json *.toml *.yaml *.yml 2>/dev/null

1.2 技術スタックの検出

# JavaScript/TypeScript
ls package.json tsconfig.json 2>/dev/null

# Python
ls pyproject.toml setup.py requirements*.txt 2>/dev/null

# Mobile
ls pubspec.yaml 2>/dev/null          # Flutter
ls android/build.gradle 2>/dev/null   # Android
ls ios/*.xcodeproj 2>/dev/null        # iOS

# Other
ls Cargo.toml 2>/dev/null             # Rust
ls go.mod 2>/dev/null                 # Go
ls Gemfile 2>/dev/null                # Ruby

1.3 リポジトリ構造の種類

パターン	検出方法	意味
モノレポ	packages/、apps/、または package.json 内の workspaces	複数のプロジェクトでツールを共有
フルスタックモノリス	同じリポジトリに frontend/ と backend/ がある	単一のチームで密結合
関心事の分離	フロントエンドまたはバックエンドのコードのみ	リポジトリを分割し、個別にデプロイ
マイクロサービス	複数の service-* またはドメイン別ディレクトリ	分散アーキテクチャ

# Detect repo structure type
if [ -d "packages" ] || [ -d "apps" ]; then
    echo "MONOREPO detected"
elif [ -d "frontend" ] && [ -d "backend" ]; then
    echo "FULL-STACK MONOLITH detected"
elif [ -d "src" ] || [ -d "app" ]; then
    # Check if it's frontend or backend
    grep -q "react\|vue\|angular" package.json 2>/dev/null && echo "FRONTEND detected"
    grep -q "fastapi\|express\|django" package.json pyproject.toml 2>/dev/null && echo "BACKEND detected"
fi

1.4 ディレクトリの対応付け

# Get directory structure (max 3 levels)
find . -type d -maxdepth 3 \
    -not -path "*/node_modules/*" \
    -not -path "*/.git/*" \
    -not -path "*/venv/*" \
    -not -path "*/__pycache__/*" \
    -not -path "*/dist/*" \
    -not -path "*/build/*" \
    2>/dev/null | head -50

# Identify key directories
for dir in src app lib core services api routes components pages hooks utils models; do
    [ -d "$dir" ] && echo "Found: $dir/"
done

1.5 エントリーポイント

# Find main entry points
ls index.ts index.js main.ts main.py app.py server.ts server.js 2>/dev/null
cat package.json 2>/dev/null | grep -A1 '"main"'
cat pyproject.toml 2>/dev/null | grep -A1 'scripts'

---

フェーズ 2：慣例の検出

変更を加える前に、既存のパターンを特定して記録してください。

2.1 コードスタイル

# Check for formatters
ls .prettierrc* .editorconfig .eslintrc* biome.json 2>/dev/null  # JS/TS
ls pyproject.toml | xargs grep -l "ruff\|black\|isort" 2>/dev/null  # Python

# Check indent style from existing files
head -20 src/**/*.ts 2>/dev/null | grep "^\s" | head -1  # tabs vs spaces

2.2 テスト環境

# JS/TS testing
grep -l "jest\|vitest\|mocha\|playwright" package.json 2>/dev/null
ls jest.config.* vitest.config.* playwright.config.* 2>/dev/null

# Python testing
grep -l "pytest\|unittest" pyproject.toml 2>/dev/null
ls pytest.ini conftest.py 2>/dev/null

# Test directories
ls -d tests/ test/ __tests__/ spec/ 2>/dev/null

2.3 CI/CD 環境

# Check existing workflows
ls -la .github/workflows/ 2>/dev/null
ls .gitlab-ci.yml Jenkinsfile .circleci/ 2>/dev/null

# Check deploy configs
ls vercel.json render.yaml fly.toml railway.json Dockerfile 2>/dev/null

2.4 ドキュメントのスタイル

# Find README pattern
head -30 README.md 2>/dev/null

# Find existing docs
ls -la docs/ documentation/ wiki/ 2>/dev/null
ls CONTRIBUTING.md CHANGELOG.md 2>/dev/null

---

フェーズ 3：ガードレールの監査

存在するガードレールと、不足しているものを確認してください。

3.1 コミット前フックの状態

# Check for hook managers
ls .husky/ 2>/dev/null && echo "Husky installed"
ls .pre-commit-config.yaml 2>/dev/null && echo "pre-commit framework installed"
ls .git/hooks/pre-commit 2>/dev/null && echo "Manual pre-commit hook exists"

# Check what hooks run
cat .husky/pre-commit 2>/dev/null
cat .pre-commit-config.yaml 2>/dev/null

3.2 リンティングの状態

# JS/TS linting
grep -q "eslint" package.json && echo "ESLint configured"
grep -q "biome" package.json && echo "Biome configured"
ls .eslintrc* biome.json 2>/dev/null

# Python linting
grep -q "ruff" pyproject.toml && echo "Ruff configured"
grep -q "flake8" pyproject.toml setup.cfg && echo "Flake8 configured"

3.3 型チェックの状態

# TypeScript
ls tsconfig.json 2>/dev/null && echo "TypeScript configured"
grep "strict" tsconfig.json 2>/dev/null

# Python type checking
grep -q "mypy" pyproject.toml && echo "mypy configured"
grep -q "pyright" pyproject.toml && echo "pyright configured"
ls py.typed 2>/dev/null

3.4 コミットメッセージの強制

# commitlint
ls commitlint.config.* 2>/dev/null && echo "commitlint configured"
cat .husky/commit-msg 2>/dev/null
grep "conventional" package.json 2>/dev/null

3.5 セキュリティスキャン

# Check for security tools
grep -q "detect-secrets\|trufflehog" .pre-commit-config.yaml package.json 2>/dev/null
ls .github/workflows/*.yml | xargs grep -l "security\|audit" 2>/dev/null

---

フェーズ 4：ガードレールの整備

不足しているガードレールだけを追加してください。既存の設定を上書きしてはいけません。

4.1 JavaScript/TypeScript プロジェクト

Husky + lint-staged（未導入の場合）

# Check if already installed
if [ ! -d ".husky" ]; then
    # Install Husky
    npm install -D husky lint-staged
    npx husky init

    # Create pre-commit hook
    echo 'npx lint-staged' > .husky/pre-commit
    chmod +x .husky/pre-commit
fi

lint-staged の設定（存在しない場合は package.json に追加）：

{
  "lint-staged": {
    "*.{ts,tsx,js,jsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,md,yml,yaml}": [
      "prettier --write"
    ]
  }
}

ESLint（未導入の場合）

# Check if eslint exists
if ! grep -q "eslint" package.json; then
    npm install -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin
fi

eslint.config.js（ESLint 9 以降のフラット設定）：

import eslint from '@eslint/js'
import tseslint from 'typescript-eslint'

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.recommended,
  {
    rules: {
      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
      '@typescript-eslint/explicit-function-return-type': 'off',
      'no-console': ['warn', { allow: ['warn', 'error'] }]
    }
  },
  {
    ignores: ['dist/', 'node_modules/', 'coverage/']
  }
)

Prettier（未導入の場合）

if ! grep -q "prettier" package.json; then
    npm install -D prettier
fi

.prettierrc（既存のスタイルを尊重するか、妥当なデフォルト値を使用）：

{
  "semi": false,
  "singleQuote": true,
  "trailingComma": "es5",
  "tabWidth": 2,
  "printWidth": 100
}

commitlint（未導入の場合）

if [ ! -f "commitlint.config.js" ]; then
    npm install -D @commitlint/cli @commitlint/config-conventional
    echo "npx commitlint --edit \$1" > .husky/commit-msg
    chmod +x .husky/commit-msg
fi

commitlint.config.js：

export default {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore', 'ci', 'perf', 'revert']
    ],
    'subject-case': [2, 'always', 'lower-case'],
    'subject-max-length': [2, 'always', 72]
  }
}

4.2 Python プロジェクト

pre-commit フレームワーク（未導入の場合）

# Install pre-commit
if [ ! -f ".pre-commit-config.yaml" ]; then
    pip install pre-commit
    pre-commit install
fi

.pre-commit-config.yaml：

repos:
  # Ruff - linting and formatting (replaces black, isort, flake8)
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.14.13
    hooks:
      - id: ruff
        args: [--fix, --exit-non-zero-on-fix]
      - id: ruff-format

  # Type checking
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.16.0
    hooks:
      - id: mypy
        additional_dependencies: [types-requests]
        args: [--ignore-missing-imports]

  # Security
  - repo: https://github.com/Yelp/detect-secrets
    rev: v1.5.0
    hooks:
      - id: detect-secrets
        args: ['--baseline', '.secrets.baseline']

  # General
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files
      - id: check-merge-conflict

  # Commit messages
  - repo: https://github.com/compilerla/conventional-pre-commit
    rev: v4.0.0
    hooks:
      - id: conventional-pre-commit
        stages: [commit-msg]

pyproject.toml への追加（未設定の場合）

[tool.ruff]
target-version = "py312"
line-length = 100

[tool.ruff.lint]
select = [
    "E",   # pycodestyle errors
    "F",   # pyflakes
    "I",   # isort
    "B",   # flake8-bugbear
    "UP",  # pyupgrade
    "S",   # flake8-bandit (security)
]
ignore = ["E501"]  # line length handled by formatter

[tool.mypy]
python_version = "3.12"
strict = true
ignore_missing_imports = true

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-v --cov=src --cov-report=term-missing --cov-fail-under=80"

4.3 ブランチ保護（ユーザー向けの説明）

次の GitHub ブランチ保護ルールを推奨します。

## Recommended Branch Protection (main branch)

1. **Require pull request before merging**
   - Require 1 approval
   - Dismiss stale reviews on new commits

2. **Require status checks**
   - Lint
   - Type check
   - Tests
   - Security scan

3. **Require signed commits** (optional but recommended)

4. **Do not allow bypassing above settings**

---

フェーズ 5：構造を維持するためのルール

絶対にしてはいけないこと

• ディレクトリ構造を再編成しない - 既存のパターンに沿って作業する
• 「一貫性」のためにファイル名を変更しない - 既存の命名規則に合わせる
• 新しいパターンを追加しない - コードベースにすでにあるパターンを使う
• インポートのスタイルを変更しない - 既存のスタイル（相対パスか絶対パスかなど）に合わせる
• フォーマットを変更しない - 既存のスタイルに合わせるか、既存のフォーマッター設定を使う
• 新しい依存関係を安易に追加しない - 同等のものがすでに存在するか確認する

必ず行うこと

• まず既存のコードを読む - 新しいコードを書く前にパターンを理解する
• 既存の慣例に合わせる - 命名、構造、エラー処理
• 既存のユーティリティを使う - すでにあるものを作り直さない
• 既存のテストパターンに従う - テストファイルの命名と構造を合わせる
• 既存の設定を維持する - 追加のみを行い、バグ修正の場合を除いて変更しない

規約の検出チェックリスト

コードを書く前に、次の項目を特定してください。

規約	例	確認する場所
命名規則	camelCase vs snake_case	既存のファイル名
ファイル構成	feature/ vs type/	ディレクトリ構成
エクスポート形式	default vs named	既存のモジュール
エラー処理	throw vs return Error	既存の関数
ロギング	console vs logger	既存のコード
テスト	describe/it vs test()	既存のテスト
コメント	JSDoc vs inline	既存のコード

---

フェーズ 6：分析レポートのテンプレート

分析を実行した後、次のレポートを作成してください。

# Repository Analysis Report

## Overview
- **Repo Type**: [Monorepo | Full-Stack | Frontend | Backend | Microservices]
- **Primary Language**: [TypeScript | Python | ...]
- **Framework**: [React | FastAPI | ...]
- **Age**: [X commits, Y contributors]

## Directory Structure

[tree output]

## Tech Stack
| Category | Technology | Config File |
|----------|------------|-------------|
| Language | TypeScript | tsconfig.json |
| Framework | React | - |
| Testing | Vitest | vitest.config.ts |
| Linting | ESLint | eslint.config.js |
| Formatting | Prettier | .prettierrc |

## Guardrails Status

### Present
- [x] ESLint configured
- [x] Prettier configured
- [x] TypeScript strict mode

### Missing (Recommended)
- [ ] Pre-commit hooks (Husky + lint-staged)
- [ ] Commit message validation (commitlint)
- [ ] Security scanning in CI

## Conventions Detected
| Pattern | Observed | Example |
|---------|----------|---------|
| Naming | camelCase | `getUserById.ts` |
| Imports | Absolute | `@/components/Button` |
| Testing | Colocated | `Button.test.tsx` |
| Exports | Named | `export { Button }` |

## Recommendations
1. Add Husky + lint-staged for pre-commit hooks
2. Add commitlint for conventional commits
3. Add security workflow to GitHub Actions

## Files to Review First
- `src/index.ts` - Main entry point
- `src/utils/` - Shared utilities
- `tests/setup.ts` - Test configuration

---

段階的な導入戦略

すべてのガードレールを一度に追加しないでください。次のスケジュールに従ってください。

週	重点項目	理由
1	フォーマット（Prettier/Ruff）	破壊的変更がなく、すぐに効果が得られる
2	リンティング（ESLint/Ruff）	明らかな問題を検出できる
3	コミット前フック	1～2週目の作業を自動化する
4	コミットメッセージの検証	チーム内の一貫性を保つ
5	型チェックの厳格化	実行時エラーを検出できる
6	セキュリティスキャン	脆弱性を検出できる

---

別々のリポジトリでの作業

フロントエンドとバックエンドが別々のリポジトリにある場合：

フロントエンドリポジトリの設定

# Clone and analyze
git clone [frontend-repo]
cd frontend

# Run analysis
# Expect: React/Vue/Angular, no backend code

# Add frontend-specific guardrails
# - Husky + lint-staged
# - ESLint + Prettier
# - Component testing (Vitest/Jest)

バックエンドリポジトリの設定

# Clone and analyze
git clone [backend-repo]
cd backend

# Run analysis
# Expect: FastAPI/Express/Django, no frontend code

# Add backend-specific guardrails
# - pre-commit framework
# - Ruff + mypy
# - API testing (pytest/Jest)

リポジトリ間の連携

課題	解決策
共有型	OpenAPI 仕様から生成する
API コントラクト	コントラクトテスト（Pact）
デプロイ	CI/CD トリガーを使って連携する
バージョン管理	両方でセマンティックバージョニングを使用する

---

アンチパターン

• 使われないガードレールの追加 - チームが使うものだけを追加する
• 初日から厳格なルールを適用 - 段階的に導入する
• 警告によるブロック - 最初は寛容にし、時間をかけて厳格化する
• 既存のパターンを無視 - 既存のものに合わせて作業する
• 過剰な設計 - 複雑なシステムよりシンプルなルールを優先する
• 分析フェーズを省略 - 変更する前に必ず現状を把握する

---

クイックリファレンス：検出コマンド

# One-liner repo analysis
echo "=== Repo Type ===" && \
ls -d packages apps frontend backend 2>/dev/null || echo "Standard repo" && \
echo "=== Tech Stack ===" && \
ls *.json *.toml *.yaml 2>/dev/null && \
echo "=== Existing Guardrails ===" && \
ls .husky .pre-commit-config.yaml .eslintrc* 2>/dev/null || echo "None detected" && \
echo "=== Entry Points ===" && \
ls index.* main.* app.* server.* 2>/dev/null