set-up-project

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Set up project

设置项目

Scaffold and audit the per-repo configuration the skills assume:

Rules file:
```
AGENTS.md
```
, which every harness reads.
```
CLAUDE.md
```
is either the single line
```
@AGENTS.md
```
or a symlink to
```
AGENTS.md
```
. Claude Code skips a project's
```
AGENTS.md
```
when a
```
CLAUDE.md
```
exists, and both of those forms give it the same text.
Issue tracker: where issues live (GitHub by default; local markdown is also supported out of the box)
Triage labels: the strings used for the five canonical triage roles
Domain docs: where
```
GLOSSARY.md
```
and ADRs live, and the consumer rules for reading them
Folder standard: the
```
.gitignore
```
lines of orchestrating/folder-standard.md
Allow-only project permissions: the global rules are the machine's safety rails, and a project's own harness files only add convenience. The audit flags every project file that weakens a global rule.

You explore, present what you found, confirm with the user, then write. Running it again is the audit.

搭建并审计这些 skill 所依赖的各仓库配置：

规则文件：
```
AGENTS.md
```
，所有 harness 都会读取它。
```
CLAUDE.md
```
要么只包含一行
```
@AGENTS.md
```
，要么是指向
```
AGENTS.md
```
的符号链接。Claude Code 在项目中存在
```
CLAUDE.md
```
时会跳过该项目的
```
AGENTS.md
```
，而这两种形式都会为它提供相同的文本。
Issue tracker：issue 所在的位置（默认使用 GitHub；也开箱即用地支持本地 Markdown）
Triage 标签：五个标准 triage 角色所使用的字符串
Domain 文档：
```
GLOSSARY.md
```
和 ADR 的存放位置，以及读取它们的 consumer 规则
目录规范：orchestrating/folder-standard.md 中的
```
.gitignore
```
配置行
仅允许（allow-only）的项目权限：全局规则是机器的安全护栏，而项目自身的 harness 文件只能增加便利性。审计会标出每个削弱全局规则的项目文件。

你先进行探索，展示发现，与用户确认，然后才写入。再次运行即为审计。

Process

流程

1. Check the machine

1. 检查机器

Run set-up-machine's verify script,

python3 <set-up-machine skill>/scripts/verify.py

(the skill is installed beside this one). A pass is exit code 0. That means the

rules

line says

ok

and no

hook

line says

FAIL

. A

codex

line that says

differs

same

stricter

, or

skipped

is not a failure.

differs

is what the script prints for a row Codex can't express, and it still exits 0 with

rules ok

. When the exit code is not 0, run the set-up-machine skill first, then come back. Done when verify exits 0.

运行 set-up-machine 的验证脚本：

python3 <set-up-machine skill>/scripts/verify.py

（该 skill 安装在此 skill 旁边）。退出码为 0 即表示通过。这意味着

rules

行显示

ok

，且没有任何

hook

行显示

FAIL

。

codex

行显示

differs

、

same

、

stricter

或

skipped

均不属于失败。

differs

是脚本在 Codex 无法表达某一行时输出的结果；此时脚本仍会在

rules ok

的情况下以 0 退出。退出码不是 0 时，先运行 set-up-machine skill，然后返回本流程。验证脚本以 0 退出即完成。

2. Explore

2. 探索

Look at the current repo to understand its starting state. Read whatever exists; don't assume:

```
git remote -v
```
and
```
.git/config
```
: is this a GitHub repo? Which one?
```
AGENTS.md
```
and
```
CLAUDE.md
```
at the repo root: does either exist? Is there already an
```
## Agent skills
```
or
```
## Environment defaults
```
section in either?
```
GLOSSARY.md
```
and
```
GLOSSARY-MAP.md
```
at the repo root, and any
```
CONTEXT.md
```
or
```
CONTEXT-MAP.md
```
in the repo: the domain docs' old names, which the skills no longer read
```
docs/adr/
```
and any
```
src/*/docs/adr/
```
directories
```
docs/agents/
```
: does this skill's prior output already exist?
```
.efforts/
```
: a sign that a local-markdown issue tracker is already in use
```
docs/assets/
```
: the folder standard's old image folder
Is the
```
triage
```
skill installed? (a
```
triage
```
skill folder alongside this one, or
```
triage
```
in your available skills.) This decides whether Section B runs at all.
Monorepo signals: a
```
pnpm-workspace.yaml
```
, a
```
workspaces
```
field in
```
package.json
```
, or a populated
```
packages/*
```
with its own
```
src/
```
. These are present only in a genuinely large multi-package repo; their absence means single-context, which is almost every repo.
A tool the project's own docs require for a role skills name (a worktree tool in a
```
docs/worktrees.md
```
, a session host its scripts assume). This decides whether Section D runs.

查看当前仓库以了解其初始状态。读取已有内容；不要想当然：

```
git remote -v
```
和
```
.git/config
```
：这是 GitHub 仓库吗？是哪个仓库？
仓库根目录的
```
AGENTS.md
```
和
```
CLAUDE.md
```
：是否存在其中之一？其中是否已经包含
```
## Agent skills
```
或
```
## Environment defaults
```
部分？
仓库根目录的
```
GLOSSARY.md
```
和
```
GLOSSARY-MAP.md
```
，以及仓库中的任何
```
CONTEXT.md
```
或
```
CONTEXT-MAP.md
```
：这些是 domain 文档的旧名称，而相关 skill 已不再读取它们
```
docs/adr/
```
以及任何
```
src/*/docs/adr/
```
目录
```
docs/agents/
```
：此 skill 之前是否已经生成过相应输出？
```
.efforts/
```
：是否已有使用本地 Markdown issue tracker 的迹象
```
docs/assets/
```
：目录规范中的旧图片目录
是否安装了
```
triage
```
skill？（当前 skill 旁边是否有
```
triage
```
skill 文件夹，或可用 skills 中是否列有
```
triage
```
。）这决定是否执行 B 节。
Monorepo 信号：是否存在
```
pnpm-workspace.yaml
```
、
```
package.json
```
中的
```
workspaces
```
字段，或已填充且各自带有
```
src/
```
的
```
packages/*
```
。这些信号只会在真正的大型多包仓库中出现；没有这些信号就表示采用 single-context，而几乎所有仓库都是如此。
项目自身文档为某个 role skill 所要求的工具（
```
docs/worktrees.md
```
中的 worktree 工具，或其脚本所假设的 session host）。这决定是否执行 D 节。

3. Present findings and ask

3. 展示发现并询问

Summarise what's present and what's missing. Then take the sections in order. One section, one answer, then the next.

Lead each section with the recommended answer so the user can accept it in a word. Give a one-line explainer only when the choice genuinely branches; skip the section entirely when exploration already settled it (Section B when

triage

isn't installed, Section C when there's no monorepo and no old

CONTEXT.md

CONTEXT-MAP.md

, Section D when the project names no tool for a role).

Section A: Issue tracker.

Explainer: The "issue tracker" is where issues live for this repo. Skills like
to-tickets
,
triage
, and
to-spec
read from and write to it. They need to know whether to call
gh issue create
, write a markdown file under
.efforts/
, or follow some other workflow you describe. Pick the place you actually track work for this repo.

Default posture: these skills were designed for GitHub. If a

git remote

points at GitHub, propose that. If a

git remote

points at GitLab (

gitlab.com

or a self-hosted host), propose GitLab. Otherwise (or if the user prefers), offer:

GitHub: issues live in the repo's GitHub Issues (uses the
```
gh
```
CLI)
GitLab: issues live in the repo's GitLab Issues (uses the
```
glab
```
CLI)
Local markdown: issues live as files under
```
.efforts/<effort>/
```
in this repo (good for solo projects or repos without a remote)
Other (Jira, Linear, etc.): ask the user to describe the workflow in one paragraph; the skill will record it as freeform prose

Record the choice in

docs/agents/issue-tracker.md

. The GitHub and GitLab templates carry a "PRs as a request surface" flag, defaulted off. Leave it off and don't raise it: a user who wants external PRs in the triage queue can flip the flag in the file later.

Section B: Triage label vocabulary. Skip this section entirely if the

triage

skill isn't installed (exploration told you), since an uninstalled skill needs no labels.

If it is installed, ask exactly one question:

Do you want to keep the default triage labels? (recommended: yes)

The defaults are the five canonical roles, each label string equal to its name:

needs-triage

needs-info

ready-for-agent

ready-for-human

wontfix

. On yes, write them as-is. Only if the user says no, usually because their tracker already uses other names (e.g.

bug:triage

for

needs-triage

), collect the overrides so

triage

applies existing labels instead of creating duplicates.

Section C: Domain docs. Default to single-context (one

GLOSSARY.md

docs/adr/

at the repo root). This fits almost every repo; write it without asking.

Offer multi-context (a root

GLOSSARY-MAP.md

pointing to per-context

GLOSSARY.md

files) only when exploration found monorepo signals. Then confirm which layout they want.

When exploration found an old

CONTEXT.md

CONTEXT-MAP.md

, propose renaming each with

git mv

, so its history follows it:

git mv CONTEXT.md GLOSSARY.md

git mv CONTEXT-MAP.md GLOSSARY-MAP.md

, and the same for each per-context

CONTEXT.md

. Where the new name already exists,

git mv

refuses: propose merging the old file into the new one instead, and ask which wins where they disagree. Also propose updating the map's links and any other file that names the old files; the drafts of

AGENTS.md

and

docs/agents/domain.md

already use the new names.

When exploration found a

docs/assets/

folder, propose moving each topic with

git mv

, as the folder standard's Migration from older layouts says: images the project ships or shows to

assets/images/<topic>/

, screenshots to

assets/screenshots/<topic>/

, and each relative link to them updated.

Section D: Project environment defaults. Recommend none. Ask only when exploration found a tool the project requires for a role: then propose an

## Environment defaults

row for it, which overrides the user's global row for this project. agents-md.md, Environment defaults, says what may go there.

总结已有和缺失的内容。然后按顺序处理各节。每节只问一个问题，得到一个答案后再进入下一节。

每节先给出建议答案，让用户可以用一个词接受。只有当选项确实会产生不同分支时才提供一行说明；如果探索阶段已经确定了答案，则整节跳过（未安装

triage

时跳过 B 节；没有 monorepo 且不存在旧

CONTEXT.md

或

CONTEXT-MAP.md

时跳过 C 节；项目未为任何 role 指定工具时跳过 D 节）。

A 节：Issue tracker。

说明：“issue tracker”是此仓库中 issue 的存放位置。
to-tickets
、
triage
和
to-spec
等 skill 会从中读取 issue 并向其写入 issue。它们需要知道是应调用
gh issue create
、在
.efforts/
下写入 Markdown 文件，还是遵循你描述的其他工作流。请选择你实际用于跟踪此仓库工作的地方。

默认方案：这些 skill 是围绕 GitHub 设计的。如果

git remote

指向 GitHub，则建议使用 GitHub。如果

git remote

指向 GitLab（

gitlab.com

或自托管主机），则建议使用 GitLab。其他情况（或如果用户另有偏好）则提供以下选项：

GitHub：issue 存放在仓库的 GitHub Issues 中（使用
```
gh
```
CLI）
GitLab：issue 存放在仓库的 GitLab Issues 中（使用
```
glab
```
CLI）
本地 Markdown：issue 作为文件存放在此仓库的
```
.efforts/<effort>/
```
下（适合个人项目或没有 remote 的仓库）
其他（Jira、Linear 等）：让用户用一段话描述工作流；skill 会将其记录为自由格式文本

将选择记录在

docs/agents/issue-tracker.md

中。GitHub 和 GitLab 模板包含一个“PRs as a request surface”标志，默认关闭。保持关闭且不要主动提起：如果用户希望将外部 PR 加入 triage 队列，之后可以自行在文件中启用该标志。

B 节：Triage 标签词汇。 如果未安装

triage

skill，则整节跳过（探索阶段已经确定），因为未安装的 skill 不需要标签。

如果已安装，则只问一个问题：

你想保留默认的 triage 标签吗？（建议：是）

默认值为五个标准角色，每个标签字符串都与其角色名相同：

needs-triage

、

needs-info

、

ready-for-agent

、

ready-for-human

、

wontfix

。用户回答是时，原样写入。只有用户回答否时——通常是因为其 tracker 已经使用其他名称（例如用

bug:triage

表示

needs-triage

）——才收集覆盖值，使

triage

沿用现有标签，而不是创建重复标签。

C 节：Domain 文档。 默认采用 single-context（仓库根目录下一个

GLOSSARY.md

和

docs/adr/

）。它适合几乎所有仓库；无需询问，直接写入。

只有探索发现 monorepo 信号时，才提供 multi-context（根目录的

GLOSSARY-MAP.md

指向各 context 的

GLOSSARY.md

）选项。然后确认他们想要哪种布局。

当探索发现旧

CONTEXT.md

或

CONTEXT-MAP.md

时，建议使用

git mv

重命名每个文件，使其历史记录随文件一起保留：

git mv CONTEXT.md GLOSSARY.md

、

git mv CONTEXT-MAP.md GLOSSARY-MAP.md

，每个 context 下的

CONTEXT.md

也执行同样操作。如果新名称已经存在，

git mv

会拒绝执行：建议改为将旧文件合并到新文件中，并询问双方内容不一致时以哪一方为准。还应建议更新 map 中的链接以及所有引用旧文件名的其他文件；

AGENTS.md

和

docs/agents/domain.md

的草稿已经使用新名称。

当探索发现

docs/assets/

文件夹时，按照目录规范中的从旧布局迁移建议，使用

git mv

移动各个主题：项目附带或展示的图片移至

assets/images/<topic>/

，截图移至

assets/screenshots/<topic>/

，并更新指向它们的每条相对链接。

D 节：项目环境默认值。 建议设为无。只有当探索发现项目为某个 role 所需工具时才询问：此时为该工具提出一个

## Environment defaults

行，它会覆盖此项目中用户的全局行。agents-md.md 的 Environment defaults 部分说明了其中可以写什么。

4. Confirm and write

4. 确认并写入

Show the user a draft of:

```
AGENTS.md
```
: new from agents-md.md, or the existing one with the
```
## Agent skills
```
block and any
```
## Environment defaults
```
rows added, and each line of an existing
```
CLAUDE.md
```
moved into it
```
CLAUDE.md
```
: the single line
```
@AGENTS.md
```
, or an existing symlink to
```
AGENTS.md
```
left as it is. Claude Code skips a project's
```
AGENTS.md
```
when a
```
CLAUDE.md
```
exists, and both forms give it the same text.
```
.gitignore
```
:
```
.scratch/
```
and
```
.claude/worktrees/
```
, each only where it's missing

The contents of

docs/agents/issue-tracker.md

docs/agents/domain.md

, and

docs/agents/triage-labels.md

(the last only when

triage

is installed)

Each rename or merge of an old
```
CONTEXT.md
```
or
```
CONTEXT-MAP.md
```
, and the edits to the files that name them, when Section C proposed them
Each move out of
```
docs/assets/
```
, and the links it updates, when proposed

Let them edit, then take one approval for all of it. Then write:

Edit
```
AGENTS.md
```
, never
```
CLAUDE.md
```
. If an
```
## Agent skills
```
block already exists, update its contents in place rather than appending a duplicate, and keep the user's edits around it. Include the
```
### Triage labels
```
sub-block only when
```
triage
```
is installed and Section B ran.
Leave
```
CLAUDE.md
```
holding
```
@AGENTS.md
```
alone (a
```
CLAUDE.md
```
that is a symlink to
```
AGENTS.md
```
is fine as it is), and add the missing
```
.gitignore
```
lines.
Write the docs files using the seed templates in this skill folder as a starting point:
- issue-tracker-github.md: GitHub issue tracker
- issue-tracker-gitlab.md: GitLab issue tracker
- issue-tracker-local.md: local-markdown issue tracker
- triage-labels.md: label mapping (only if
```
triage
```
  is installed)
- domain.md: domain doc consumer rules + layout
For "other" issue trackers, write
```
docs/agents/issue-tracker.md
```
from scratch using the user's description.
Give every
```
docs/agents/issue-tracker.md
```
the templates'
```
## Title prefixes
```
section, so each skill that creates an issue titles it the same way. Seed its semantic list from the areas the project's open issue titles already name, one line each with what the area covers.
Run each approved rename or merge of an old
```
CONTEXT.md
```
or
```
CONTEXT-MAP.md
```
, then update the files that named it.
Run each approved move out of
```
docs/assets/
```
, then update the links to it.

Done when every approved change is made.

向用户展示以下内容的草稿：

```
AGENTS.md
```
：根据 agents-md.md 新建，或在现有文件基础上添加
```
## Agent skills
```
块和任何
```
## Environment defaults
```
行，并将现有
```
CLAUDE.md
```
中的每一行移入其中
```
CLAUDE.md
```
：仅一行
```
@AGENTS.md
```
，或保持现有指向
```
AGENTS.md
```
的符号链接不变。Claude Code 在项目中存在
```
CLAUDE.md
```
时会跳过该项目的
```
AGENTS.md
```
，而这两种形式都会为它提供相同的文本。
```
.gitignore
```
：补充
```
.scratch/
```
和
```
.claude/worktrees/
```
，且仅在对应行缺失时添加

docs/agents/issue-tracker.md

、

docs/agents/domain.md

和

docs/agents/triage-labels.md

的内容（仅在安装了

triage

时包含最后一个文件）

对旧
```
CONTEXT.md
```
或
```
CONTEXT-MAP.md
```
的每次重命名或合并，以及 C 节建议对这些文件所做的相关修改
从
```
docs/assets/
```
移出的每个文件，以及建议更新的相关链接

让用户自行编辑，然后对全部内容进行一次审批。审批后执行：

编辑
```
AGENTS.md
```
，绝不编辑
```
CLAUDE.md
```
。如果已经存在
```
## Agent skills
```
块，则原地更新其内容，而不是追加重复块，并保留用户在其周围所做的编辑。仅当安装了
```
triage
```
且执行过 B 节时，才加入
```
### Triage labels
```
子块。
让
```
CLAUDE.md
```
保持只含
```
@AGENTS.md
```
的状态不变（
```
CLAUDE.md
```
是指向
```
AGENTS.md
```
的符号链接也无需改动），并补充缺失的
```
.gitignore
```
行。
使用此 skill 文件夹中的种子模板作为起点写入文档文件：
- issue-tracker-github.md：GitHub issue tracker
- issue-tracker-gitlab.md：GitLab issue tracker
- issue-tracker-local.md：本地 Markdown issue tracker
- triage-labels.md：标签映射（仅在安装了
```
triage
```
  时）
- domain.md：domain 文档 consumer 规则和布局
对于其他 issue tracker，根据用户的描述从头编写
```
docs/agents/issue-tracker.md
```
。
为每个
```
docs/agents/issue-tracker.md
```
写入模板中的
```
## Title prefixes
```
部分，使每个创建 issue 的 skill 都采用一致方式命名。根据项目现有开放 issue 标题中提到的领域生成语义列表，每个领域占一行，并说明其涵盖内容。
执行所有已批准的对旧
```
CONTEXT.md
```
或
```
CONTEXT-MAP.md
```
的重命名或合并，然后更新引用这些旧文件名的文件。
执行所有已批准的从
```
docs/assets/
```
移出文件的操作，然后更新指向这些文件的链接。

完成所有已批准的更改即告完成。

5. Audit

5. 审计

Read every harness file the project holds, from the root down, against set-up-machine's

rules.json

, whether or not that harness is set up on this machine:

.claude/settings.json

and

settings.local.json

.cursor/cli.json

opencode.json(c)

and

.opencode/

.codex/config.toml

. references/project-files.md says what each harness lets a project file do to a global rule, and how to judge an entry. Report each finding as:

```
weakens
```
: a global rule no longer holds as the machine sets it, in some harness. Explain which and why, and propose the fix: remove the entry, or narrow it to the project's own commands. The file is the project's, so change it only on the user's approval.
```
overlaps
```
: an allow that covers a rule's command while the rule still holds. Propose narrowing it.
```
extra
```
(a project deny or ask) and
```
gap
```
(what you can't judge): name each.

Also report each old

CONTEXT.md

CONTEXT-MAP.md

still in the repo, with the rename Section C proposes for it. Report a

docs/agents/issue-tracker.md

that has no

## Title prefixes

section, and propose the section step 3 writes.

The audit passes with no

weakens

. Done when it passes, or the user has chosen to keep a

weakens

entry: then it stays failed, and the report names that entry.

读取项目持有的每个 harness 文件（从根目录向下），依据 set-up-machine 的

rules.json

进行检查，无论该 harness 是否已在此机器上设置：

.claude/settings.json

和

settings.local.json

、

.cursor/cli.json

、

opencode.json(c)

和

.opencode/

、

.codex/config.toml

。references/project-files.md 说明了每个 harness 允许项目文件对全局规则执行哪些操作，以及如何判断某个条目。

将每项发现报告为：

```
weakens
```
：某个 harness 中的全局规则不再保持机器所设定的状态。说明是哪一个规则以及原因，并提出修复方案：移除该条目，或将其收窄到项目自己的命令。该文件属于项目，因此只有在用户批准后才能更改。
```
overlaps
```
：一条 allow 覆盖某条规则的命令，但该规则仍然成立。建议将其收窄。
```
extra
```
（项目级 deny 或 ask）和
```
gap
```
（无法判断的内容）：分别列出每一项。

还要报告仓库中仍然存在的每个旧

CONTEXT.md

或

CONTEXT-MAP.md

，并给出 C 节建议的重命名方案。如果

docs/agents/issue-tracker.md

缺少

## Title prefixes

部分，也要报告，并提出第 3 步会写入该部分。

审计在没有

weakens

的情况下通过。审计通过即完成；如果用户选择保留某条

weakens

，它仍保持失败状态，报告必须点名该条目。

6. Done

6. 完成

Tell the user the setup is complete, what the audit found, and which skills will now read from these files. Mention they can edit

AGENTS.md

and

docs/agents/*.md

directly later; re-running this skill audits the project again, and switches issue trackers when they want to. Leave the commit to the user or the skill that called this one.

告知用户设置已完成、审计发现了什么，以及哪些 skill 现在会读取这些文件。说明用户以后可以直接编辑

AGENTS.md

和

docs/agents/*.md

；再次运行此 skill 会重新审计项目，并可在用户需要时切换 issue tracker。将 commit 操作留给用户或调用此 skill 的 skill 处理。