AgentSkillsCN

new-project-scaffold

在提交代码之前，务必确保 README.md 和 .cursor/project_architecture.md 完全更新且准确无误。README.md 必须作为一份完整、详尽的分步操作指南，用于应用程序的运行与日常维护。这样可以有效防止因文档陈旧、残缺或误导性信息而导致的提交失败。

SKILL.md
--- frontmatter
name: new-project-scaffold
description: Scaffolds a brand-new project with a clean, best-practice folder structure, pinned latest-stable dependencies, and a Docker Compose–ready layout. Designed to bootstrap production-ready codebases from day one.

Skill: New Project Scaffold

Purpose

Create a production-oriented project foundation before any feature development begins.
This skill ensures the project starts with:

  1. •A clear, layered folder structure
  2. •Latest stable dependencies, properly pinned
  3. •A Docker Compose–ready setup that runs consistently across environments

The goal is to avoid early technical debt and make the project immediately runnable, testable, and deployable.

When to Run

Run this skill when:

  • •The user says they are starting a new project
  • •The user asks to scaffold, bootstrap, or initialize a codebase
  • •The user wants a clean structure before writing any logic
  • •The user explicitly wants the project to be Docker-ready from the beginning

Output Expectations

By the end of this skill, the agent should deliver:

  • •A complete folder and file layout
  • •Clear dependency choices (language/framework aware)
  • •Docker and Docker Compose configuration that can run immediately
  • •A README that explains how to start the project

Step-by-Step Workflow

Step 1: Determine the Stack

From user input (or defaults if not specified), infer:

  • •Programming language (e.g. Node.js, Python, Go)
  • •Framework (if any)
  • •Runtime expectations (e.g. Node 20 LTS, Python 3.11+)

If unclear, assume modern defaults and state them explicitly.

Step 2: Generate a Best-Practice Folder Structure

Use a layered, intention-revealing layout.
Avoid placing application logic in the project root.

Generic Scaffold Template (adapt as needed)

project-root/ ├── src/ # Application source code │ └── main.* # Single entrypoint (framework-specific) ├── tests/ # Unit/integration tests ├── config/ # Non-secret configuration ├── scripts/ # Dev, build, or deployment scripts ├── docs/ # Optional: design docs, ADRs, runbooks ├── docker/ # Optional: Dockerfile(s), overrides ├── .env.example # Environment variable template (no secrets) ├── .gitignore ├── .dockerignore ├── README.md ├── docker-compose.yml └── [lockfile] # package-lock.json / poetry.lock / go.sum

Structural Rules

  • •Exactly one application entrypoint
  • •Tests live outside src/
  • •No secrets committed (ever)
  • •Configurable values come from environment variables
  • •Framework conventions may override naming, but not layering

For stack-specific layouts (Node/TypeScript, Python, Go) and Docker Compose with a database, see reference.md.

Step 3: Select and Pin Latest Stable Dependencies

Dependency rules are strict:

  • •Use latest stable releases only
  • •Avoid alpha, beta, rc, next, or preview tags
  • •Pin versions explicitly
  • •Always include and commit a lockfile

Stability Verification

  • •Node.js: Use LTS (e.g. Node 20), confirm latest npm tag
  • •Python: Stable PyPI releases only, no --pre
  • •Go: Tagged semantic versions only

Document:

  • •Runtime version
  • •Package manager version (if relevant)

Step 4: Make It Docker Compose–Ready

Assume the project will be containerized.

Required Files

  • •Dockerfile
  • •docker-compose.yml
  • •.dockerignore
  • •.env.example

Docker Rules

  • •No secrets inside images or compose files
  • •All runtime config via environment variables
  • •One service initially (the app)
  • •Additional services (DB, cache) added only when needed
  • •Prefer official base images and pin tags (e.g. postgres:16-alpine)

Minimal docker-compose.yml

services: app: build: . env_file: .env ports: - "${APP_PORT:-8080}:8080"

Minimal .env.example

APP_PORT=8080 NODE_ENV=development

DATABASE_URL=

Step 5: Create README.md

The README must answer only what a new developer needs:

  • •What the project is
  • •Required runtime
  • •How to run locally
  • •How to run with Docker Compose

Avoid deep architecture explanations (those belong in /docs).

Constraints (Do Not Violate)

  • •Do not introduce secrets
  • •Do not assume experimental dependencies
  • •Do not over-engineer (no microservices on day one)
  • •Do not create unused folders or files
  • •Do not omit Docker readiness

Quality Checklist

Before finishing, ensure:

  • • Folder structure is clean and layered
  • • Dependencies are pinned to latest stable versions
  • • Lockfile is included
  • • Dockerfile and docker-compose.yml work together
  • • .env.example lists all required env vars
  • • .dockerignore reduces build context
  • • README explains how to start the project

Expected Outcome

After running this skill:

  • •The project can be started immediately
  • •Local and Docker environments behave consistently
  • •The codebase is structured for long-term maintainability
  • •Future features can be added without restructuring

This skill establishes a strong technical foundation before any business logic exists.

Additional Resources

  • •For language/framework-specific structure and examples, see reference.md.