setting-up-projects

用途

该技能用于自动化项目设置，为新项目或已有项目建立最佳实践、质量工具链和规范配置。其核心理念是“从一开始就保证质量”，通过自动化质量检查、统一格式与代码规范、尽早发现密钥与安全漏洞、以及合理的初始配置来提升开发效率。

激活时机

当出现以下情况时激活：

用户正在创建新项目
项目缺少 pre-commit 钩子配置
缺少必要配置文件（.gitignore、.editorconfig 等）
设置开发环境
用户询问项目设置或最佳实践
建立质量基线

主要能力

1. 评估当前状态

检查现有配置文件与 Git 状态，识别缺失项，包括：.gitignore、.editorconfig、包管理器配置（package.json、requirements.txt 等）、代码检查配置、格式化配置、pre-commit 钩子、CI/CD 配置。

2. 创建核心配置

.gitignore：生成语言特定（node_modules、pycache 等）、IDE 文件（.vscode、.idea 等）、操作系统文件（.DS_Store、Thumbs.db 等）、环境文件（.env、.env.local）、构建产物（dist/、build/、*.pyc）的忽略模式。
.editorconfig：确保跨编辑器格式一致，示例配置包含 root = true、indent_style = space、indent_size = 2、end_of_line = lf、charset = utf-8、trim_trailing_whitespace = true、insert_final_newline = true，并针对 [.py] 设置 indent_size = 4，针对 [.md] 设置 trim_trailing_whitespace = false。

3. 设置质量工具

Python 项目：使用 Ruff（快速一体化工具，替代 black、flake8、isort）进行代码检查与格式化；使用 Pyright 或 Mypy 进行类型检查。pyproject.toml 配置示例包含 [tool.ruff] 的 line-length = 100、target-version = "py311"，[tool.ruff.lint] 的 select = ["E", "F", "I", "N", "W"]，以及 [tool.pyright] 的 typeCheckingMode = "basic"。
JavaScript/TypeScript 项目：使用 Prettier 进行代码格式化，ESLint 进行代码检查。.prettierrc 示例包含 semi: true、singleQuote: true、tabWidth: 2、trailingComma: "es5"；.eslintrc.json 示例包含 extends: ["eslint:recommended"]、env: { node: true, es2021: true }。

4. 安装 Pre-commit 钩子

Pre-commit 在每次提交前自动运行检查。安装命令：

pip install pre-commit
pre-commit install

配置（.pre-commit-config.yaml）示例：

Python 项目：包含通用检查（trailing-whitespace、end-of-file-fixer、check-yaml、check-json、check-merge-conflict、check-added-large-files 且 --maxkb=500）、Ruff（ruff --fix、ruff-format）、Pyright 类型检查、detect-secrets 密钥检测（--baseline .secrets.baseline）。
JavaScript/TypeScript 项目：包含通用检查、Prettier（types_or: [javascript, jsx, ts, tsx, json, yaml, markdown]）、ESLint（files: .[jt]sx?$、types: [file]）、detect-secrets。

5. 初始化基线

针对已有项目，创建基线以避免标记既有问题：

detect-secrets scan > .secrets.baseline
pre-commit run --all-files

6. 文档化设置

创建或更新 README.md，包含设置说明、开发工作流、使用的质量工具、如何运行测试、如何贡献。

语言特定设置

Python：必要文件包括 requirements.txt 或 pyproject.toml、.python-version、pytest.ini 或 pyproject.toml；虚拟环境命令：python -m venv venv、source venv/bin/activate（Windows 为 venv\Scripts\activate）、pip install -r requirements.txt。
JavaScript/TypeScript：必要文件包括 package.json、tsconfig.json、.nvmrc；安装依赖：npm install 或 yarn install。
Rust：必要文件包括 Cargo.toml、rustfmt.toml、clippy.toml；设置命令：cargo build、cargo fmt、cargo clippy。
Go：必要文件包括 go.mod、.golangci.yml；设置命令：go mod download、go fmt ./...、go vet ./...。

配置模板

完整 Python 项目结构：包含 .gitignore、.editorconfig、.pre-commit-config.yaml、pyproject.toml、README.md、requirements.txt、requirements-dev.txt、src/project/init.py、tests/init.py。
完整 JavaScript 项目结构：包含 .gitignore、.editorconfig、.pre-commit-config.yaml、.prettierrc、.eslintrc.json、package.json、tsconfig.json、README.md、src/index.ts、tests/index.test.ts。

集成点

调用 Builder Agent 进行代码生成；使用语言特定模板；pre-commit 设置参考 Specs/PreCommitHooks.md；项目结构参考 Specs/ProjectStructure.md；最佳实践参考语言特定指南；模板位于 ~/.amplihack/.claude/templates/。

示例工作流

用户表示“我正在为一个 REST API 启动新的 Python 项目”时，技能会制定设置计划，创建项目结构、pre-commit 钩子、Python 配置（ruff、pyright）、Git 忽略模式、README 模板，并给出安装步骤：

python -m venv venv
source venv/bin/activate
pip install -r requirements-dev.txt
pre-commit install
pre-commit run --all-files

质量检查清单

完成设置前需确认：所有必要配置存在、pre-commit 钩子已安装并测试、README 记录设置过程、.gitignore 覆盖常见模式、质量工具已配置、依赖已记录、提供示例 .env 文件（不含密钥）、测试目录已创建。

常见错误与避免

没有 .gitignore：导致提交不需要的文件；应先创建全面的 .gitignore。
格式不一致：导致合并冲突；应设置 Prettier/Black 和 .editorconfig。
没有 pre-commit 钩子：问题在 CI 或代码审查后期才被发现；应从一开始安装。
硬编码密钥：凭据被提交到 Git；应使用 .env 文件加 detect-secrets 钩子。
缺少类型检查：类型错误在运行时才被发现；应从一开始启用 TypeScript/Mypy。
没有文档：新开发者难以设置；应维护清晰的 README。

成功标准

良好的项目设置应满足：开发者可在 5 分钟内克隆并运行、质量检查自动运行、团队格式一致、仓库中无密钥、文档清晰、贡献者摩擦最小。

限制

资料未提供该技能的具体收费、价格、平台支持范围、实际效果数据或使用步骤的更多细节。

技能介绍

用途