Back to Details

existing-repo

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Existing Repository Skill

现有代码仓库操作技能

Load with: base.md + security.md
For working with existing codebases - analyze structure, respect conventions, and set up proper guardrails without breaking anything.
Sources: Husky | lint-staged | pre-commit | commitlint
加载依赖：base.md + security.md
适用于现有代码库的处理场景——分析结构、遵循约定、在不破坏现有内容的前提下设置合理的防护机制。
参考工具： Husky | lint-staged | pre-commit | commitlint

Core Principle

核心原则

Understand before modifying. Existing repos have conventions, patterns, and history. Your job is to work within them, not reorganize them.
修改前先理解。 现有代码仓库有其自身的约定、模式和历史。你的工作是在现有框架内开展，而非重新组织架构。

Phase 1: Repository Analysis

阶段1：代码仓库分析

ALWAYS run this analysis first when joining an existing repo.
加入任何现有代码仓库时，务必先执行此分析步骤。

1.1 Basic Detection

1.1 基础检测

bash
undefined
bash
undefined

Check git status

检查Git状态

git remote -v 2>/dev/null git branch -a 2>/dev/null git log --oneline -5 2>/dev/null
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
undefined
ls -la .* 2>/dev/null | head -20 ls *.json *.toml *.yaml *.yml 2>/dev/null
undefined

1.2 Tech Stack Detection

1.2 技术栈检测

bash
undefined
bash
undefined

JavaScript/TypeScript

JavaScript/TypeScript

ls package.json tsconfig.json 2>/dev/null
ls package.json tsconfig.json 2>/dev/null

Python

Python

ls pyproject.toml setup.py requirements*.txt 2>/dev/null
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
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
undefined
ls Cargo.toml 2>/dev/null # Rust ls go.mod 2>/dev/null # Go ls Gemfile 2>/dev/null # Ruby
undefined

1.3 Repo Structure Type

1.3 仓库结构类型

PatternDetectionMeaning
Monorepo
packages/
, 
apps/
, 
workspaces
in package.json		Multiple projects, shared tooling
Full-Stack Monolith
frontend/
+ 
backend/
in same repo		Single team, tightly coupled
Separate ConcernsOnly frontend OR backend codeSplit repos, separate deploys
MicroservicesMultiple 
service-*
or domain dirs		Distributed architecture
bash
undefined
模式检测方式含义
单体仓库（Monorepo）存在
packages/
、
apps/
目录，或package.json中包含
workspaces
包含多个项目，共享工具链
全栈单体仓库同一仓库中同时存在
frontend/
和
backend/
目录		单一团队维护，前后端紧耦合
单一职责仓库仅包含前端或后端代码代码库拆分，独立部署
微服务仓库存在多个
service-*
或领域相关目录		分布式架构
bash
undefined

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
undefined
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 # 检查是前端还是后端 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
undefined

1.4 Directory Mapping

1.4 目录映射

bash
undefined
bash
undefined

Get directory structure (max 3 levels)

获取目录结构（最多3层）

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
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
undefined
for dir in src app lib core services api routes components pages hooks utils models; do [ -d "$dir" ] && echo "Found: $dir/" done
undefined

1.5 Entry Points

1.5 入口文件

bash
undefined
bash
undefined

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'

---
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'

---

Phase 2: Convention Detection

阶段2：约定检测

Identify and document existing patterns before making changes.
在进行任何修改前，先识别并记录现有模式。

2.1 Code Style

2.1 代码风格

bash
undefined
bash
undefined

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
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
undefined
head -20 src/**/*.ts 2>/dev/null | grep "^\s" | head -1 # 制表符vs空格
undefined

2.2 Testing Setup

2.2 测试环境配置

bash
undefined
bash
undefined

JS/TS testing

JS/TS测试工具

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

Python testing

Python测试工具

grep -l "pytest|unittest" pyproject.toml 2>/dev/null ls pytest.ini conftest.py 2>/dev/null
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
undefined
ls -d tests/ test/ tests/ spec/ 2>/dev/null
undefined

2.3 CI/CD Setup

2.3 CI/CD配置

bash
undefined
bash
undefined

Check existing workflows

检查现有工作流

ls -la .github/workflows/ 2>/dev/null ls .gitlab-ci.yml Jenkinsfile .circleci/ 2>/dev/null
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
undefined
ls vercel.json render.yaml fly.toml railway.json Dockerfile 2>/dev/null
undefined

2.4 Documentation Style

2.4 文档风格

bash
undefined
bash
undefined

Find README pattern

查找README模式

head -30 README.md 2>/dev/null
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

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

---

Phase 3: Guardrails Audit

阶段3：防护机制审计

Check what guardrails exist and what's missing.
检查现有防护机制，识别缺失项。

3.1 Pre-commit Hooks Status

3.1 提交前钩子状态

bash
undefined
bash
undefined

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"
ls .husky/ 2>/dev/null && echo "Husky已安装" ls .pre-commit-config.yaml 2>/dev/null && echo "pre-commit框架已安装" ls .git/hooks/pre-commit 2>/dev/null && echo "存在手动配置的pre-commit钩子"

Check what hooks run

检查运行的钩子

cat .husky/pre-commit 2>/dev/null cat .pre-commit-config.yaml 2>/dev/null
undefined
cat .husky/pre-commit 2>/dev/null cat .pre-commit-config.yaml 2>/dev/null
undefined

3.2 Linting Status

3.2 代码检查状态

bash
undefined
bash
undefined

JS/TS linting

JS/TS代码检查

grep -q "eslint" package.json && echo "ESLint configured" grep -q "biome" package.json && echo "Biome configured" ls .eslintrc* biome.json 2>/dev/null
grep -q "eslint" package.json && echo "ESLint已配置" grep -q "biome" package.json && echo "Biome已配置" ls .eslintrc* biome.json 2>/dev/null

Python linting

Python代码检查

grep -q "ruff" pyproject.toml && echo "Ruff configured" grep -q "flake8" pyproject.toml setup.cfg && echo "Flake8 configured"
undefined
grep -q "ruff" pyproject.toml && echo "Ruff已配置" grep -q "flake8" pyproject.toml setup.cfg && echo "Flake8已配置"
undefined

3.3 Type Checking Status

3.3 类型检查状态

bash
undefined
bash
undefined

TypeScript

TypeScript

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

Python type checking

Python类型检查

grep -q "mypy" pyproject.toml && echo "mypy configured" grep -q "pyright" pyproject.toml && echo "pyright configured" ls py.typed 2>/dev/null
undefined
grep -q "mypy" pyproject.toml && echo "mypy已配置" grep -q "pyright" pyproject.toml && echo "pyright已配置" ls py.typed 2>/dev/null
undefined

3.4 Commit Message Enforcement

3.4 提交消息规范

bash
undefined
bash
undefined

commitlint

commitlint

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

3.5 Security Scanning

3.5 安全扫描

bash
undefined
bash
undefined

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

---
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

---

Phase 4: Guardrails Setup

阶段4：防护机制搭建

Only add missing guardrails. Never overwrite existing configurations.
仅添加缺失的防护机制，绝不覆盖现有配置。

4.1 JavaScript/TypeScript Projects

4.1 JavaScript/TypeScript项目

Husky + lint-staged (if not present)

Husky + lint-staged（若未安装）

bash
undefined
bash
undefined

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 config** (add to package.json if missing):

```json
{
  "lint-staged": {
    "*.{ts,tsx,js,jsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,md,yml,yaml}": [
      "prettier --write"
    ]
  }
}
if [ ! -d ".husky" ]; then # 安装Husky npm install -D husky lint-staged npx husky init
# 创建pre-commit钩子
echo 'npx lint-staged' > .husky/pre-commit
chmod +x .husky/pre-commit
fi

**lint-staged配置**（若缺失则添加至package.json）：

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

ESLint (if not present)

ESLint（若未安装）

bash
undefined
bash
undefined

Check if eslint exists

检查ESLint是否存在

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

**eslint.config.js** (ESLint 9+ flat config):

```javascript
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/']
  }
)
if ! grep -q "eslint" package.json; then npm install -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin fi

**eslint.config.js**（ESLint 9+ 扁平化配置）：

```javascript
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 not present)

Prettier（若未安装）

bash
if ! grep -q "prettier" package.json; then
    npm install -D prettier
fi
.prettierrc (respect existing style or use sensible defaults):
json
{
  "semi": false,
  "singleQuote": true,
  "trailingComma": "es5",
  "tabWidth": 2,
  "printWidth": 100
}
bash
if ! grep -q "prettier" package.json; then
    npm install -D prettier
fi
.prettierrc（遵循现有风格或使用合理默认值）：
json
{
  "semi": false,
  "singleQuote": true,
  "trailingComma": "es5",
  "tabWidth": 2,
  "printWidth": 100
}

commitlint (if not present)

commitlint（若未安装）

bash
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:
javascript
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]
  }
}
bash
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：
javascript
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 Projects

4.2 Python项目

pre-commit framework (if not present)

pre-commit框架（若未安装）

bash
undefined
bash
undefined

Install pre-commit

安装pre-commit

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

**.pre-commit-config.yaml**:

```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]
if [ ! -f ".pre-commit-config.yaml" ]; then pip install pre-commit pre-commit install fi

**.pre-commit-config.yaml**：

```yaml
repos:
  # Ruff - 代码检查与格式化（替代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

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

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

  # 通用检查
  - 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

  # 提交消息规范
  - repo: https://github.com/compilerla/conventional-pre-commit
    rev: v4.0.0
    hooks:
      - id: conventional-pre-commit
        stages: [commit-msg]

pyproject.toml additions (if not present)

pyproject.toml补充配置（若缺失）

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"
toml
[tool.ruff]
target-version = "py312"
line-length = 100

[tool.ruff.lint]
select = [
    "E",   # pycodestyle错误
    "F",   # pyflakes
    "I",   # isort
    "B",   # flake8-bugbear
    "UP",  # pyupgrade
    "S",   # flake8-bandit（安全检查）
]
ignore = ["E501"]  # 行长度由格式化工具处理

[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 Branch Protection (Document for User)

4.3 分支保护（为用户提供文档）

Recommend these GitHub branch protection rules:
markdown
undefined
推荐以下GitHub分支保护规则：
markdown
undefined

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

---
  1. 合并前需要拉取请求
    • 需要1次审批
    • 新提交时自动驳回过时的评审意见
  2. 需要状态检查通过
    • 代码检查
    • 类型检查
    • 测试
    • 安全扫描
  3. 需要签名提交（可选但推荐）
  4. 不允许绕过上述设置

---

Phase 5: Structure Preservation Rules

阶段5：结构保留规则

NEVER Do These

绝对禁止操作

  • Don't reorganize directory structure - Work within existing patterns
  • Don't rename files for "consistency" - Match existing naming conventions
  • Don't add new patterns - Use patterns already in the codebase
  • Don't change import styles - Match existing (relative vs absolute, etc.)
  • Don't change formatting - Match existing style or use existing formatter config
  • Don't add new dependencies lightly - Check if equivalent exists
  • 不要重新组织目录结构 - 在现有模式下工作
  • 不要为了“一致性”重命名文件 - 匹配现有命名约定
  • 不要添加新的模式 - 使用代码库中已有的模式
  • 不要修改导入风格 - 匹配现有风格（相对路径vs绝对路径等）
  • 不要修改格式化风格 - 匹配现有风格或使用已有的格式化配置
  • 不要轻易添加新依赖 - 先检查是否有等效的现有依赖

ALWAYS Do These

必须遵守操作

  • Read existing code first - Understand patterns before writing new code
  • Match existing conventions - Naming, structure, error handling
  • Use existing utilities - Don't reinvent what exists
  • Follow existing test patterns - Match test file naming and structure
  • Preserve existing configs - Only add, don't modify unless fixing bugs
  • 先阅读现有代码 - 在编写新代码前理解现有模式
  • 匹配现有约定 - 命名、结构、错误处理
  • 使用现有工具函数 - 不要重复造轮子
  • 遵循现有测试模式 - 匹配测试文件的命名和结构
  • 保留现有配置 - 仅添加，除非修复bug否则不修改

Convention Detection Checklist

约定检测清单

Before writing any code, identify:
ConventionExampleWhere to Check
NamingcamelCase vs snake_caseExisting file names
File structurefeature/ vs type/Directory layout
Export styledefault vs namedExisting modules
Error handlingthrow vs return ErrorExisting functions
Loggingconsole vs loggerExisting code
Testingdescribe/it vs test()Existing tests
CommentsJSDoc vs inlineExisting code
在编写任何代码前，先识别：
约定类型示例检查位置
命名风格小驼峰 vs 下划线命名现有文件名
文件结构按功能划分 vs 按类型划分目录布局
导出风格默认导出 vs 命名导出现有模块
错误处理抛出异常 vs 返回错误对象现有函数
日志风格console输出 vs 专用日志工具现有代码
测试风格describe/it vs test()现有测试
注释风格JSDoc vs 内联注释现有代码

Phase 6: Analysis Report Template

阶段6：分析报告模板

After running analysis, generate this report:
markdown
undefined
完成分析后，生成以下报告：
markdown
undefined

Repository Analysis Report

代码仓库分析报告

Overview

概述

  • Repo Type: [Monorepo | Full-Stack | Frontend | Backend | Microservices]
  • Primary Language: [TypeScript | Python | ...]
  • Framework: [React | FastAPI | ...]
  • Age: [X commits, Y contributors]
  • 仓库类型：[单体仓库 | 全栈仓库 | 前端仓库 | 后端仓库 | 微服务仓库]
  • 主要语言：[TypeScript | Python | ...]
  • 框架：[React | FastAPI | ...]
  • 仓库规模：[X次提交，Y位贡献者]

Directory Structure

目录结构

[tree output]
[tree命令输出结果]

Tech Stack

技术栈

CategoryTechnologyConfig File
LanguageTypeScripttsconfig.json
FrameworkReact-
TestingVitestvitest.config.ts
LintingESLinteslint.config.js
FormattingPrettier.prettierrc
分类技术配置文件
编程语言TypeScripttsconfig.json
开发框架React-
测试工具Vitestvitest.config.ts
代码检查ESLinteslint.config.js
代码格式化Prettier.prettierrc

Guardrails Status

防护机制状态

Present

已配置

  • ESLint configured
  • Prettier configured
  • TypeScript strict mode
  • ESLint已配置
  • Prettier已配置
  • TypeScript严格模式已启用

Missing (Recommended)

缺失（推荐配置）

  • Pre-commit hooks (Husky + lint-staged)
  • Commit message validation (commitlint)
  • Security scanning in CI
  • 提交前钩子（Husky + lint-staged）
  • 提交消息验证（commitlint）
  • CI中的安全扫描

Conventions Detected

已识别的约定

PatternObservedExample
NamingcamelCase
getUserById.ts
ImportsAbsolute
@/components/Button
TestingColocated
Button.test.tsx
ExportsNamed
export { Button }
模式已观测到示例
命名风格小驼峰
getUserById.ts
导入风格绝对路径
@/components/Button
测试文件位置与源码同目录
Button.test.tsx
导出风格命名导出
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
  1. 添加Husky + lint-staged作为提交前钩子
  2. 添加commitlint以规范提交消息
  3. 在GitHub Actions中添加安全扫描工作流

Files to Review First

优先查看的文件

  • src/index.ts
    - Main entry point
  • src/utils/
    - Shared utilities
  • tests/setup.ts
    - Test configuration

---
  • src/index.ts
    - 主入口文件
  • src/utils/
    - 共享工具函数目录
  • tests/setup.ts
    - 测试配置文件

---

Gradual Implementation Strategy

逐步实施策略

Don't add all guardrails at once. Follow this timeline:
WeekFocusWhy
1Formatting (Prettier/Ruff)Non-breaking, easy wins
2Linting (ESLint/Ruff)Catches obvious issues
3Pre-commit hooksAutomates week 1-2
4Commit message validationTeam consistency
5Type checking strictnessCatches runtime errors
6Security scanningCatches vulnerabilities
不要一次性添加所有防护机制，遵循以下时间线：
周重点原因
1代码格式化（Prettier/Ruff）无破坏性改动，快速见效
2代码检查（ESLint/Ruff）捕获明显问题
3提交前钩子自动化第1-2周的工作
4提交消息验证保持团队一致性
5严格类型检查捕获运行时错误
6安全扫描捕获漏洞

Working with Separate Repos

多仓库协作场景

When frontend and backend are in separate repos:
当前端和后端位于不同仓库时：

Frontend Repo Setup

前端仓库配置

bash
undefined
bash
undefined

Clone and analyze

克隆并分析

git clone [frontend-repo] cd frontend
git clone [前端仓库地址] cd frontend

Run analysis

执行分析

Expect: React/Vue/Angular, no backend code

预期：React/Vue/Angular，无后端代码

Add frontend-specific guardrails

添加前端专用防护机制

- Husky + lint-staged

- Husky + lint-staged

- ESLint + Prettier

- ESLint + Prettier

- Component testing (Vitest/Jest)

- 组件测试（Vitest/Jest）

undefined
undefined

Backend Repo Setup

后端仓库配置

bash
undefined
bash
undefined

Clone and analyze

克隆并分析

git clone [backend-repo] cd backend
git clone [后端仓库地址] cd backend

Run analysis

执行分析

Expect: FastAPI/Express/Django, no frontend code

预期：FastAPI/Express/Django，无前端代码

Add backend-specific guardrails

添加后端专用防护机制

- pre-commit framework

- pre-commit框架

- Ruff + mypy

- Ruff + mypy

- API testing (pytest/Jest)

- API测试（pytest/Jest）

undefined
undefined

Cross-Repo Coordination

跨仓库协作方案

ConcernSolution
Shared typesGenerate from OpenAPI spec
API contractsContract testing (Pact)
DeploymentsCoordinate via CI/CD triggers
VersioningSemantic versioning on both
关注点解决方案
共享类型从OpenAPI规范生成
API契约契约测试（Pact）
部署协调通过CI/CD触发器同步
版本管理双方均使用语义化版本

Anti-Patterns

反模式

  • Adding unused guardrails - Only add what the team will use
  • Strict rules on day 1 - Introduce gradually
  • Blocking on warnings - Start permissive, tighten over time
  • Ignoring existing patterns - Work with what exists
  • Over-engineering - Simple rules > complex systems
  • Skipping the analysis phase - Always understand before changing
  • 添加未使用的防护机制 - 仅添加团队会实际使用的工具
  • 第一天就启用严格规则 - 逐步引入
  • 因警告阻止提交 - 初始宽松，逐步收紧
  • 忽略现有模式 - 适配现有代码库
  • 过度设计 - 简单规则优于复杂系统
  • 跳过分析阶段 - 永远先理解再修改

Quick Reference: Detection Commands

快速参考：检测命令

bash
undefined
bash
undefined

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
undefined
echo "=== 仓库类型 ===" &&
ls -d packages apps frontend backend 2>/dev/null || echo "标准仓库" &&
echo "=== 技术栈 ===" &&
ls .json .toml .yaml 2>/dev/null &&
echo "=== 现有防护机制 ===" &&
ls .husky .pre-commit-config.yaml .eslintrc 2>/dev/null || echo "未检测到防护机制" &&
echo "=== 入口文件 ===" &&
ls index. main. app.* server.* 2>/dev/null
undefined