setup-project-md

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Setup PROJECT.md

设置PROJECT.md

Overview

概述

One-shot setup: combine codebase evidence with user-supplied product context into a single root

PROJECT.md

that answers what this project is and how it fits together. Do not treat this as an ongoing maintenance skill unless the user explicitly asks to regenerate or update the file.

一次性设置流程：将代码库信息与用户提供的产品上下文相结合，在仓库根目录生成一份独立的PROJECT.md文档，回答项目定位及各部分关联方式。除非用户明确要求重新生成或更新该文件，否则请勿将此流程视为持续维护操作。

Output

输出

Write exactly one file: repo-root
```
PROJECT.md
```
.
If
```
PROJECT.md
```
already exists, ask once whether to overwrite, merge/update, or abort. Do not silently overwrite.

仅生成一个文件：仓库根目录的
```
PROJECT.md
```
。
若
```
PROJECT.md
```
已存在，需询问用户是否覆盖、合并/更新或终止操作，不得静默覆盖。

Workflow

工作流程

1. Map the codebase

1. 梳理代码库

Inspect enough to describe the system accurately:

Root docs:
```
README.md
```
, architecture notes, deploy docs, env examples (names only — never copy secret values).
Manifests and tooling: package managers, workspaces, apps/packages layout, CI, Docker, infra entrypoints.
Runtime shape: entrypoints, routes, major domains/modules, data stores, queues, external services.
Product surfaces: web app, API, CLI, workers, admin, docs site — only what exists.

Prefer evidence from the repo over marketing claims. Mark inferences clearly.

充分检查代码库以准确描述系统：

根目录文档：
```
README.md
```
、架构说明、部署文档、环境示例（仅记录名称——切勿复制敏感值）。
清单与工具：包管理器、工作区、应用/包结构、CI、Docker、基础设施入口。
运行结构：入口文件、路由、核心领域/模块、数据存储、队列、外部服务。
产品载体：Web应用、API、CLI、工作进程、后台管理、文档站点——仅记录实际存在的内容。

优先参考仓库中的实际证据，而非营销描述。明确标记推断内容。

2. Collect user context

2. 收集用户上下文

Ask for product facts the code cannot fully answer. Batch questions. Cover:

Mission / problem solved and non-goals.
Target users and primary use cases.
Business model or distribution (if relevant).
Current stage (prototype, beta, production) and known constraints.
Important history, ownership, or decisions agents routinely miss.
Links to live product, design, or issue tracker (optional).

If the user provides a brief up front, use it and only ask for missing critical gaps. If they decline interview, proceed with labeled assumptions.

询问代码无法完全体现的产品信息，批量提出问题，涵盖：

使命/解决的问题及非目标。
目标用户与核心使用场景。
商业模式或分发方式（如相关）。
当前阶段（原型、测试版、正式版）及已知约束。
重要历史、归属信息或Agent通常会忽略的决策。
产品线上版本、设计稿或问题追踪器的链接（可选）。

若用户预先提供了简要信息，可直接使用并仅询问缺失的关键内容。若用户拒绝回答，则基于标注的假设继续操作。

3. Reconcile code vs narrative

3. 协调代码与叙事

Prefer code and configs for structure, stack, and commands.
Prefer user input for intent, audience, roadmap, and business context.
Call out contradictions and resolve with the user when they affect the overview.

结构、技术栈及命令优先参考代码与配置。
意图、受众、路线图及业务上下文优先参考用户输入。
若存在矛盾且会影响概述内容，需向用户指出并解决。

4. Write PROJECT.md

4. 编写PROJECT.md

Use references/template.md. Fill applicable sections; omit empty ones. Quality bar:

A new agent can understand purpose, surfaces, layout, and how to run after reading once.
Distinguishes product intent from implementation map.
Concrete paths and commands, not vague architecture essays.
No secrets; env vars by name only.
Honest about unknowns and WIP areas.

使用references/template.md模板。填充适用章节，省略空白章节。质量标准：

新Agent阅读后即可理解项目目的、载体、结构及运行方式。
区分产品意图与实现架构。
提供具体路径与命令，而非模糊的架构描述。
不含敏感信息；仅记录环境变量（env vars）名称。
如实标注未知内容与开发中（WIP）的区域。

5. Link from AGENTS.md (conditional)

5. 链接至AGENTS.md（可选）

After

PROJECT.md

exists:

Check for root
```
AGENTS.md
```
only.
If it does not exist, skip linking. Do not create
```
AGENTS.md
```
.
If it exists, add a clear pointer to
```
PROJECT.md
```
if missing:
- Prefer an existing Index / Docs / Related docs section.
- Otherwise add a short section such as
```
## Project docs
```
  with a bullet:
```
- [PROJECT.md](PROJECT.md) — product and codebase overview
```
- Do not duplicate the full overview into
```
AGENTS.md
```
  .
- Preserve unrelated
```
AGENTS.md
```
  content.

生成

PROJECT.md

后：

仅检查根目录的
```
AGENTS.md
```
。
若
```
AGENTS.md
```
不存在，跳过链接步骤，请勿创建
```
AGENTS.md
```
。
若
```
AGENTS.md
```
存在，若缺失链接则添加指向
```
PROJECT.md
```
的明确指针：
- 优先添加至现有“索引/文档/相关文档”章节。
- 若无上述章节，可添加简短章节如
```
## 项目文档
```
  ，并添加列表项：
```
- [PROJECT.md](PROJECT.md) — 产品与代码库概述
```
- 请勿将完整概述内容复制到
```
AGENTS.md
```
  中。
- 保留
```
AGENTS.md
```
  中无关内容。

6. Deliver

6. 交付

Confirm path written.
Brief summary: one-line purpose, main surfaces, and whether
```
AGENTS.md
```
was updated or skipped.
Do not commit unless the user asks.

确认文件写入路径。
简要总结：一行说明文档用途、核心载体，以及是否更新或跳过了
```
AGENTS.md
```
的链接操作。
除非用户要求，否则请勿提交代码。

Isolation

独立性

This skill stands alone. Do not mention, link to, or depend on other skills. Reference only repo files, user input, and this skill's

references/

此流程独立运行。请勿提及、链接或依赖其他流程。仅参考仓库文件、用户输入及此流程的

references/

目录。

Out of Scope

超出范围

Replacing
```
README.md
```
or full architecture ADRs.
Implementing features or refactoring while mapping.
Creating
```
AGENTS.md
```
when missing.
Recurring audits unless the user asks to run setup again.

替代
```
README.md
```
或完整的架构决策记录（ADRs）。
在梳理代码库时实现功能或重构代码。
当
```
AGENTS.md
```
不存在时创建该文件。
定期审计，除非用户要求重新运行此设置流程。