Back to Details

project-init

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Project Init

项目初始化

Overview

概述

This skill transforms a project idea into a fully scoped, documented project blueprint through structured discovery, research, and user collaboration. The output is a project directory containing comprehensive documentation that serves as the source of truth for implementation.
该Skill通过结构化探索、研究和用户协作，将项目构想转化为范围明确、文档完备的项目蓝图。输出结果是一个包含完整文档的项目目录，作为项目实现的唯一依据。

Workflow

工作流

The workflow has two major stages: Discovery (understanding what to build) and Initialization (creating the project documentation). Complete Discovery fully before moving to Initialization.
该工作流包含两个主要阶段：探索阶段（明确构建内容）和初始化阶段（创建项目文档）。必须完成全部探索步骤后，才能进入初始化阶段。

Stage 1: Discovery

第一阶段：探索

Step 1: Gather Project Details

步骤1：收集项目详情

Begin by understanding the project at a high level. Ask the user to describe:
  • What the project is (purpose, problem it solves, target users)
  • Core features and functionality
  • Tech stack preferences (languages, frameworks, databases, infrastructure)
  • Project-type-specific details:
    • Web apps: pages/routes needed, authentication, data models
    • CLI tools: example commands/usage, input/output formats
    • APIs: endpoints, data schemas, integrations
    • Mobile apps: screens, navigation flow, platform targets
    • Libraries/SDKs: public API surface, target consumers
    • Games: mechanics, platforms, networking model
Use the 
AskUserQuestion
tool to gather this information. Start with broad questions, then drill into specifics based on answers. Do not overwhelm — ask 1-3 focused questions per round.
首先从宏观层面了解项目。请用户描述：
  • 项目内容：项目的用途、解决的问题、目标用户
  • 核心功能与特性
  • 技术栈偏好：编程语言、框架、数据库、基础设施
  • 项目类型特定细节：
    • Web应用：所需页面/路由、认证机制、数据模型
    • CLI工具：示例命令/用法、输入输出格式
    • API：端点、数据模式、集成需求
    • 移动应用：界面、导航流程、目标平台
    • 库/SDK：公开API接口、目标用户群体
    • 游戏：游戏机制、目标平台、网络模型
使用
AskUserQuestion
工具收集这些信息。先从宽泛的问题入手，再根据用户回答深入细节。避免信息过载——每轮仅提出1-3个针对性问题。

Step 2: Research

步骤2：调研

Conduct online research using the 
WebSearch
tool to investigate:
  • Similar projects — find existing implementations, open-source examples, and established patterns for this type of project
  • Technical best practices — architecture patterns, library choices, common pitfalls for the chosen tech stack
  • Trade-offs — evaluate alternative approaches discovered during research
  • Implementation details — specific APIs, protocols, or techniques the project will need
Synthesize findings internally. Identify anything the user may have missed, potential risks, and areas needing clarification.
使用
WebSearch
工具进行在线调研，内容包括：
  • 同类项目：查找现有实现、开源示例以及该类型项目的成熟模式
  • 技术最佳实践：所选技术栈的架构模式、库选择、常见陷阱
  • 方案权衡：评估调研过程中发现的替代方案
  • 实现细节：项目所需的具体API、协议或技术
整合调研结果，找出用户可能遗漏的内容、潜在风险以及需要进一步明确的地方。

Step 3: Self-Reflection

步骤3：自我反思

Before proceeding to the interview, pause and reason through:
  • Connections between user requirements and research findings
  • Gaps in the current understanding
  • Architectural implications of the stated requirements
  • Potential scope risks or technical challenges
  • Questions where the answer is NOT obvious from prior context
在进入访谈环节前，先梳理以下内容：
  • 用户需求与调研结果之间的关联
  • 当前对项目的认知缺口
  • 已明确需求对架构的影响
  • 潜在的范围风险或技术挑战
  • 无法从现有上下文得到答案的问题

Step 4: Interview

步骤4：访谈

Use the 
AskUserQuestion
tool to clarify anything unresolved from Steps 1-3. Topics may include:
  • Technical implementation choices surfaced by research
  • UI/UX decisions (for visual projects)
  • Concerns or trade-offs discovered during research
  • Feature prioritization (MVP vs. nice-to-have)
  • Design preferences and constraints
  • Integration requirements
  • Deployment and infrastructure needs
Rules for the interview:
  • Do NOT ask questions whose answers are obvious from previous responses or research
  • Do NOT ask about preferences already documented in 
    references/user-preferences.md
    — read and apply those directly
  • Continue interviewing until confident that the project is fully understood
  • Each round should surface genuinely new information
Read 
references/user-preferences.md
for standing preferences that apply to all projects (monorepo structure, Docker, Makefiles, Bash scripts). Apply these automatically without asking.
使用
AskUserQuestion
工具澄清步骤1-3中未解决的问题。话题可能包括：
  • 调研过程中发现的技术实现选择
  • UI/UX决策（针对可视化项目）
  • 调研中发现的问题或方案权衡
  • 功能优先级（MVP vs. 锦上添花的功能）
  • 设计偏好与约束
  • 集成需求
  • 部署与基础设施需求
访谈规则：
  • 不要提出答案可从之前的回复或调研结果中直接得出的问题
  • 不要询问
    references/user-preferences.md
    中已记录的偏好——直接读取并应用这些设置
  • 持续访谈，直至对项目有充分理解
  • 每轮访谈都应挖掘出真正的新信息
请阅读
references/user-preferences.md
，了解适用于所有项目的固定偏好（如单仓库结构、Docker、Makefile、Bash脚本）。这些设置将自动应用，无需询问用户。

Stage 2: Initialization

第二阶段：初始化

Proceed only after reaching full confidence in the project understanding. Initialization creates the project directory and documentation files — nothing else.
仅当对项目有充分把握后，再进入此阶段。初始化阶段仅创建项目目录和文档文件——不进行其他操作。

Step 1: Create Project Directory

步骤1：创建项目目录

bash
mkdir -p <project-name>/docs
Create only the project root and 
docs/
directory. Do NOT run any framework initializers, package managers, or scaffolding tools — those are roadmap tasks.
bash
mkdir -p <project-name>/docs
仅创建项目根目录和
docs/
目录。不要运行任何框架初始化工具、包管理器或脚手架工具——这些属于路线图中的任务。

Step 2: Create SPEC.md

步骤2：创建SPEC.md

Write 
<project-name>/docs/SPEC.md
containing:
  • Project Overview — name, purpose, problem statement, target users
  • Architecture — high-level system design, component diagram (ASCII/Mermaid), data flow
  • Tech Stack — languages, frameworks, databases, infrastructure with rationale for each choice
  • Project Structure — directory layout following monorepo conventions (see 
    references/user-preferences.md
    )
  • Core Modules — description of each major module/component, its responsibilities, and interfaces
  • Data Models — key entities, schemas, relationships
  • API Surface — endpoints, contracts, or public interfaces (as applicable)
  • External Integrations — third-party services, APIs, dependencies
  • Key Decisions — architectural decisions made during discovery with rationale
在
<project-name>/docs/SPEC.md
中写入以下内容：
  • 项目概述：项目名称、用途、问题陈述、目标用户
  • 架构设计：高层系统设计、组件图（ASCII/Mermaid格式）、数据流
  • 技术栈：编程语言、框架、数据库、基础设施，并说明每个选择的理由
  • 项目结构：遵循单仓库规范的目录布局（参考
    references/user-preferences.md
    ）
  • 核心模块：每个主要模块/组件的描述、职责与接口
  • 数据模型：关键实体、模式、关系
  • API接口：端点、契约或公开接口（如适用）
  • 外部集成：第三方服务、API、依赖项
  • 关键决策：探索阶段做出的架构决策及理由

Step 3: Create STYLES.md (Conditional)

步骤3：创建STYLES.md（可选）

Only create this file for projects with a visual/frontend component (web apps, mobile apps, desktop apps, games with UI).
Write 
<project-name>/docs/STYLES.md
containing a concise styling specification for a modern, professional, Apple-esque design:
  • Design Philosophy — clean, minimal, purposeful, premium feel
  • Color Palette — primary, secondary, accent, semantic colors (success/warning/error/info), neutral scale, dark mode variants
  • Typography — font families (system stack or specific), size scale, weight scale, line heights
  • Spacing & Layout — spacing scale, grid system, breakpoints, max-widths, container padding
  • Component Styling — buttons, inputs, cards, modals, navigation patterns, hover/focus/active states
  • Motion & Animation — transition durations, easing curves, animation principles
  • Iconography — icon style, library recommendation, sizing
  • Shadows & Elevation — shadow scale, usage guidelines
  • Border Radius — radius scale and usage
Base recommendations on modern design trends: clean whitespace, subtle depth through shadows, refined color palettes, smooth micro-interactions.
仅当项目包含可视化/前端组件（Web应用、移动应用、桌面应用、带UI的游戏）时，才创建此文件。
在
<project-name>/docs/STYLES.md
中写入简洁的样式规范，打造现代、专业、类Apple风格的设计：
  • 设计理念：简洁、极简、实用、高端质感
  • 配色方案：主色、辅助色、强调色、语义色（成功/警告/错误/信息）、中性色阶、深色模式变体
  • 排版：字体族（系统字体栈或特定字体）、字号层级、字重层级、行高
  • 间距与布局：间距规范、网格系统、断点、最大宽度、容器内边距
  • 组件样式：按钮、输入框、卡片、模态框、导航模式、悬停/聚焦/激活状态
  • 动效与动画：过渡时长、缓动曲线、动画原则
  • 图标系统：图标风格、库推荐、尺寸规范
  • 阴影与层级：阴影规范、使用指南
  • 圆角：圆角规范与使用场景
建议基于现代设计趋势：简洁留白、通过阴影营造微妙层次感、精致配色方案、流畅微交互。

Step 4: Create ROADMAP.md

步骤4：创建ROADMAP.md

Read 
references/roadmap-format.md
for the canonical format, phase structure, and action item template.
Write 
<project-name>/docs/ROADMAP.md
following these rules:
Header: 
# <project-name> Development Roadmap
followed by 
---
Phases (in order):
  1. Phase 1: Project Setup — Infrastructure, tooling, project scaffolding. Must include tasks for:
    • Running framework initializers (e.g., 
      npx create-next-app@latest
      , 
      go mod init
      )
    • Monorepo directory structure creation
    • Makefile with standard targets (
      dev
      , 
      run
      , 
      test
      , 
      check
      , plus project-specific targets)
    • Docker and docker-compose setup
    • CI/CD pipeline configuration
    • Linting, formatting, pre-commit hooks
    • For frontend apps: global styles setup, shared component library scaffold, page stubs with "X Page Coming Soon" text
    • Environment configuration templates
  2. Phase 2: Research (optional) — Only include for complex projects requiring deep technical investigation before implementation. Each task produces a deliverable in 
    ./research/
    . Skip for straightforward projects.
  3. Phase 3: MVP (or Phase 2 if Research is skipped) — Core features required for initial launch. Break into logical subsections with numbered action items.
  4. Phase 4: Nice to Have (or Phase 3) — Features, polish, and production hardening that elevate the project beyond MVP.
  5. Phase 5: Future (or Phase 4) — High-level directions, not scoped tasks. Uses the Description/Features/Rationale format instead of Description/Requirements/Implementation Notes.
Action item format for Phases 1-4: Each item gets exactly 3 subsections:
  • Description: What and why
  • Requirements: 
    - [ ]
    checklist of concrete deliverables
  • Implementation Notes: Technical guidance, references, trade-offs
Action item format for Future phase: Each item gets exactly 3 subsections:
  • Description: What this direction is about
  • Features: Potential features and capabilities
  • Rationale: Why this direction is worth pursuing
Number action items as 
<phase>.<item>
(e.g., 
1.1
, 
1.2
, 
3.1
, 
3.2
). Give each item a descriptive title after the number (e.g., 
### 1.1 Monorepo Structure and Tooling
).
Action items should be granular enough to be individually actionable but broad enough to avoid excessive fragmentation. Target 3-8 action items per phase for most projects.
阅读
references/roadmap-format.md
，了解标准格式、阶段结构和任务模板。
遵循以下规则编写
<project-name>/docs/ROADMAP.md
：
标题：
# <project-name> 开发路线图
，下方添加
---
阶段（按顺序）：
  1. 阶段1：项目搭建：基础设施、工具、项目脚手架。必须包含以下任务：
    • 运行框架初始化工具（如
      npx create-next-app@latest
      、
      go mod init
      ）
    • 创建单仓库目录结构
    • 编写包含标准目标的Makefile（
      dev
      、
      run
      、
      test
      、
      check
      以及项目特定目标）
    • Docker与docker-compose配置
    • CI/CD流水线配置
    • 代码检查、格式化、提交前钩子
    • 前端应用：全局样式设置、共享组件库脚手架、页面占位符（显示“X Page Coming Soon”文本）
    • 环境配置模板
  2. 阶段2：调研（可选）：仅适用于在实现前需要深入技术研究的复杂项目。每个任务需在
    ./research/
    中产出交付物。简单项目可跳过此阶段。
  3. 阶段3：MVP（若跳过调研阶段则为阶段2）：初始发布所需的核心功能。分解为逻辑子模块，并为每个任务编号。
  4. 阶段4：锦上添花（若跳过调研阶段则为阶段3）：超越MVP的功能、优化与生产环境加固。
  5. 阶段5：未来规划（若跳过调研阶段则为阶段4）：高层发展方向，而非具体任务。采用“描述/特性/理由”格式，而非“描述/需求/实现说明”格式。
阶段1-4的任务格式：每个任务需包含3个小节：
  • 描述：任务内容与目的
  • 需求：
    - [ ]
    格式的具体交付物清单
  • 实现说明：技术指导、参考资料、方案权衡
未来规划阶段的任务格式：每个任务需包含3个小节：
  • 描述：该发展方向的内容
  • 特性：潜在功能与能力
  • 理由：该发展方向的价值
任务编号格式为
<阶段>.<序号>
（如
1.1
、
1.2
、
3.1
、
3.2
）。编号后添加任务的描述性标题（如
### 1.1 单仓库结构与工具配置
）。
任务需细化到可独立执行的粒度，但又不能过于琐碎。大多数项目每个阶段建议设置3-8个任务。