Back to Details

project-scaffolding

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Project Scaffolding Skill

项目脚手架技能

When to Activate

触发场景

Activate this skill when:
  • Creating new projects from scratch
  • Setting up project directory structure
  • Initializing configuration files
  • Starting from BaseProject template
  • Setting up technology-specific projects
在以下场景下触发本技能：
  • 从头创建新项目
  • 搭建项目目录结构
  • 初始化配置文件
  • 基于BaseProject模板启动项目
  • 搭建特定技术栈的项目

Quick Setup Methods

快速搭建方法

MethodBest ForTime
Automated ScriptStandard projects2-3 min
Manual SetupCustom configurations10-15 min
方法适用场景耗时
自动化脚本标准项目2-3分钟
手动搭建自定义配置项目10-15分钟

Directory Naming Conventions

目录命名规范

Directories:     CamelCase (VideoProcessor, AudioTools)
Date-based:      kebab-case with YYYY-MM-DD (logs-2025-01-15)
NO spaces or underscores in directory names
Directories:     CamelCase (VideoProcessor, AudioTools)
Date-based:      kebab-case with YYYY-MM-DD (logs-2025-01-15)
NO spaces or underscores in directory names

Manual Setup Workflow

手动搭建流程

Step 1: Copy Template

步骤1：复制模板

bash
cp -r /path/to/BaseProject ~/Projects/YourProjectName/
cd ~/Projects/YourProjectName/
bash
cp -r /path/to/BaseProject ~/Projects/YourProjectName/
cd ~/Projects/YourProjectName/

Step 2: Clean Git History

步骤2：清理Git历史

bash
rm -rf .git
bash
rm -rf .git

Step 3: Customize AGENT.md

步骤3：自定义AGENT.md

Fill in project-specific sections:
markdown
undefined
填写项目专属的部分：
markdown
undefined

Project Purpose

Project Purpose

A REST API for managing inventory with real-time updates.
A REST API for managing inventory with real-time updates.

Tech Stack

Tech Stack

  • Language: Python 3.11+
  • Framework: FastAPI
  • Key Libraries: SQLAlchemy, Pydantic
  • Package Manager: UV
  • Language: Python 3.11+
  • Framework: FastAPI
  • Key Libraries: SQLAlchemy, Pydantic
  • Package Manager: UV

Architecture Notes

Architecture Notes

  • Microservices with event-driven updates
  • Redis for caching
  • PostgreSQL for persistence
undefined
  • Microservices with event-driven updates
  • Redis for caching
  • PostgreSQL for persistence
undefined

Step 4: Initialize Git

步骤4：初始化Git

bash
git init
git add .
git commit -m "chore: initialize repository from BaseProject"
bash
git init
git add .
git commit -m "chore: initialize repository from BaseProject"

Technology-Specific Setup

特定技术栈搭建

Python with UV

Python + UV

bash
uv init
cp AgentUsage/templates/pyproject.toml.example pyproject.toml
uv add fastapi uvicorn sqlalchemy
uv add --dev pytest black ruff mypy

mkdir -p src/YourProject/{core,utils,config}
mkdir -p tests/{unit,integration}
touch src/YourProject/__init__.py
bash
uv init
cp AgentUsage/templates/pyproject.toml.example pyproject.toml
uv add fastapi uvicorn sqlalchemy
uv add --dev pytest black ruff mypy

mkdir -p src/YourProject/{core,utils,config}
mkdir -p tests/{unit,integration}
touch src/YourProject/__init__.py

JavaScript/TypeScript

JavaScript/TypeScript

bash
pnpm init
pnpm add express dotenv
pnpm add -D typescript @types/node jest eslint prettier

mkdir -p src/{routes,controllers,middleware,utils}
touch src/index.ts
bash
pnpm init
pnpm add express dotenv
pnpm add -D typescript @types/node jest eslint prettier

mkdir -p src/{routes,controllers,middleware,utils}
touch src/index.ts

Go

Go

bash
go mod init github.com/user/project
mkdir -p cmd/api internal/{handlers,models,database} pkg
touch cmd/api/main.go
bash
go mod init github.com/user/project
mkdir -p cmd/api internal/{handlers,models,database} pkg
touch cmd/api/main.go

Rust

Rust

bash
cargo init
mkdir -p src/{routes,models,db}
cargo build
bash
cargo init
mkdir -p src/{routes,models,db}
cargo build

Standard Project Structure

标准项目结构

Python

Python

project/
├── src/
│   └── projectname/
│       ├── __init__.py
│       ├── main.py
│       ├── core/
│       ├── utils/
│       └── config/
├── tests/
│   ├── conftest.py
│   ├── unit/
│   └── integration/
├── pyproject.toml
├── uv.lock
├── AGENT.md
└── .gitignore
project/
├── src/
│   └── projectname/
│       ├── __init__.py
│       ├── main.py
│       ├── core/
│       ├── utils/
│       └── config/
├── tests/
│   ├── conftest.py
│   ├── unit/
│   └── integration/
├── pyproject.toml
├── uv.lock
├── AGENT.md
└── .gitignore

JavaScript

JavaScript

project/
├── src/
│   ├── index.ts
│   ├── routes/
│   ├── controllers/
│   └── utils/
├── tests/
├── package.json
├── tsconfig.json
├── AGENT.md
└── .gitignore
project/
├── src/
│   ├── index.ts
│   ├── routes/
│   ├── controllers/
│   └── utils/
├── tests/
├── package.json
├── tsconfig.json
├── AGENT.md
└── .gitignore

Secrets Setup

密钥配置

bash
undefined
bash
undefined

Create template

创建模板

cp AgentUsage/templates/secrets_template.json secrets_template.json
cp AgentUsage/templates/secrets_template.json secrets_template.json

Create actual secrets (gitignored)

创建实际密钥文件（已git忽略）

cp secrets_template.json secrets.json
cp secrets_template.json secrets.json

Verify in .gitignore

确认.gitignore中已配置

grep "secrets.json" .gitignore
undefined
grep "secrets.json" .gitignore
undefined

Task Tracking

任务跟踪

Track tasks in GitHub Issues with appropriate labels. Create initial issues for:
  • Set up project dependencies
  • Configure secrets management
  • Create initial project structure
  • Implement core business logic
  • Add unit tests
  • Set up CI/CD pipeline
在GitHub Issues中使用合适的标签跟踪任务，创建初始Issue覆盖以下内容：
  • 配置项目依赖
  • 配置密钥管理
  • 创建初始项目结构
  • 实现核心业务逻辑
  • 添加单元测试
  • 搭建CI/CD流水线

Verification Checklist

验证检查清单

bash
undefined
bash
undefined

Git initialized and clean

Git已初始化且状态干净

git status
git status

AGENT.md customized (no [Fill in:] markers)

AGENT.md已完成自定义（无[Fill in:]标记）

grep "[Fill in:" AGENT.md
grep "[Fill in:" AGENT.md

secrets.json in .gitignore

secrets.json已加入.gitignore

grep "secrets.json" .gitignore
grep "secrets.json" .gitignore

Dependencies installed

依赖已安装

uv sync # or pnpm install
uv sync # 或pnpm install

Project runs

项目可正常运行

uv run python src/projectname/main.py
undefined
uv run python src/projectname/main.py
undefined

Post-Setup Tasks

搭建后任务

  1. Create GitHub Issues for project-specific tasks
  2. Create initial code entry points
  3. Configure IDE settings and extensions
  4. Review relevant guides in AgentUsage/
  1. 为项目专属任务创建GitHub Issues
  2. 创建初始代码入口文件
  3. 配置IDE设置和扩展
  4. 查阅AgentUsage/目录下的相关指南

Common Issues

常见问题

Permission denied on scripts

脚本权限不足

bash
chmod +x setup_new_project.sh
bash
chmod +x setup_new_project.sh

Git commit fails

Git提交失败

bash
git config user.name "Your Name"
git config user.email "your.email@example.com"
bash
git config user.name "Your Name"
git config user.email "your.email@example.com"

Dependencies not installing

依赖安装失败

bash
undefined
bash
undefined

Python: Clear cache

Python：清理缓存

uv cache clean
uv cache clean

JavaScript: Fresh install

JavaScript：全新安装

rm -rf node_modules pnpm-lock.yaml pnpm install
undefined
rm -rf node_modules pnpm-lock.yaml pnpm install
undefined

Related Resources

相关资源

See 
AgentUsage/project_setup.md
and 
AgentUsage/project_structure.md
for:
  • Detailed directory patterns
  • CI/CD setup
  • Pre-commit hook installation
  • Technology-specific guides
查看
AgentUsage/project_setup.md
和
AgentUsage/project_structure.md
了解以下内容：
  • 详细目录规范
  • CI/CD搭建
  • Pre-commit钩子安装
  • 特定技术栈指南