Back to Details

archie-setup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Set up Archie

配置Archie

The conventions ship inside this bundle, so the only per-repo work is recording the facts an agent cannot guess: the gate commands, how to start the real app, and where the good test prior art lives.
Explore, present, confirm, then write. Nothing reaches disk before the user has seen the draft.
相关约定已包含在该工具包中，因此每个仓库仅需完成一项工作：记录Agent无法自动识别的关键信息，包括门禁命令、真实应用的启动方式，以及已有测试用例的存放位置。
流程为：探索信息、展示确认、写入文件。在用户确认草稿前，不会有任何内容写入磁盘。

1. Explore

1. 探索信息

Fill in every fact below from the repo. A fact is settled only when you have read the command or the path in a file. Everything else is 
unknown
— a real answer, and the one that stops a later skill from trying 
npm start
on a repo that has no such script.
FactWhere it is written
Package managerthe lockfile, 
packageManager
in 
package.json
, the CI workflow
Lint, typecheck, test, build
package.json
scripts, 
Makefile
, 
justfile
, 
nx.json
targets, 
turbo.json
, 
pyproject.toml
, 
Cargo.toml
. The CI workflow is the best source of all four: it shows which ones actually run, and how they are scoped in a monorepo
Run the app, and its portthe dev script, 
docker-compose.yml
, 
Procfile
, the README quickstart; the port in the dev server config, the e2e 
baseURL
, or 
.env.example
E2E harness
playwright.config.*
, 
cypress.config.*
, and the directory its specs sit in
Unit and integration test prior artthe existing specs. Pick one file per layer that a new test should be modelled on: recently touched, and asserting real behaviour rather than smoke-checking. Name the file, not its directory
Seed data and test credentialsseed and fixture scripts, 
.env.example
, 
docker-compose
env, the e2e global-setup file, the README
Branch convention
git branch -a
, the merged branches on the remote, and the default branch's name
Commit convention
git log --oneline -30
, a 
commitlint
or 
.czrc
config, 
CONTRIBUTING.md
unknown
is a value, not a gap. A skill that reads one asks the user rather than guessing, and there is no greenfield mode: a fresh repo takes the same path and simply records more 
unknown
s. On a greenfield repo the stack is not chosen yet, and choosing it is cross-cutting and hard to reverse — that belongs to the root Epic's scoping session and lands as an ADR, not as a setup output.
Done when every row holds either a value read out of the repo or 
unknown
.
从仓库中填写以下每一项信息。只有当你在文件中读到具体命令或路径时，该项信息才算确认；否则填写
unknown
——这是一个有效的值，能避免后续skill在没有
npm start
脚本的仓库中尝试执行该命令。
信息项查看位置
包管理器锁文件、
package.json
中的
packageManager
字段、CI工作流
代码检查、类型校验、测试、构建
package.json
脚本、
Makefile
、
justfile
、
nx.json
目标、
turbo.json
、
pyproject.toml
、
Cargo.toml
。CI工作流是获取这四项信息的最佳来源：它会展示实际运行的命令，以及在单体仓库中的作用范围
应用启动方式及端口开发脚本、
docker-compose.yml
、
Procfile
、README快速开始部分；端口可查看开发服务器配置、端到端测试的
baseURL
或
.env.example
端到端测试框架
playwright.config.*
、
cypress.config.*
，以及测试用例所在目录
单元测试与集成测试参考示例现有测试用例。为每个层级选择一个新测试可参考的文件：优先选择近期修改过、且能验证实际行为而非仅做冒烟检查的文件。需填写具体文件名，而非目录
测试数据与测试凭证数据填充与 fixture 脚本、
.env.example
、
docker-compose
环境变量、端到端测试全局设置文件、README
分支约定
git branch -a
命令输出、远程仓库已合并分支、默认分支名称
提交约定
git log --oneline -30
命令输出、
commitlint
或
.czrc
配置文件、
CONTRIBUTING.md
unknown
是一个有效值，而非缺失项。读取到该值的skill会询问用户而非自行猜测，且不存在全新项目模式：新仓库也遵循相同流程，只是会记录更多
unknown
值。对于全新仓库，技术栈尚未确定，而选择技术栈是跨领域且难以回退的决策——这属于根Epic的范围规划环节，最终会以ADR（架构决策记录）形式呈现，而非配置输出的一部分。
当每一行都填写了从仓库中读取到的值或
unknown
时，探索阶段完成。

2. Present and confirm

2. 展示并确认

One message, then wait:
  • The drafted facts block, verbatim as it will appear in 
    AGENTS.md
    .
  • Every 
    unknown
    , named, with a direct question. The user knows the port and the test login even when nothing in the repo says so, and this is the cheapest moment to get them.
  • The ignore file amendment from step 4, if one is needed.
Let the user correct the draft before anything is written.
发送一条消息后等待用户确认：
  • 拟写入
    AGENTS.md
    的信息块原文。
  • 列出所有
    unknown
    项，并附上直接的问题。用户可能知道端口和测试登录信息，即使仓库中没有相关记录，此时获取这些信息成本最低。
  • 若需要，附上步骤4中的忽略文件修改内容。
在写入任何内容前，让用户修正草稿。

3. Write the facts section

3. 写入信息部分

The facts live in a delimited section of 
AGENTS.md
at the repo root, which is already in every agent's context, so no skill needs a file to go and read:
md
<!-- archie:facts:start -->
项目信息存放在仓库根目录下
AGENTS.md
的一个分隔区域内，该文件已在所有Agent的上下文环境中，因此无需skill去读取文件：
md
<!-- archie:facts:start -->

Project facts

Project facts

  • Package manager: pnpm
  • Lint: 
    pnpm lint
  • Typecheck: 
    pnpm typecheck
  • Test: 
    pnpm test
  • Build: 
    pnpm build
  • Run the app: 
    pnpm dev
    , served on http://localhost:4200
  • E2E harness: Playwright, specs in 
    apps/web-e2e/src/
  • Unit test prior art: 
    libs/scheduling/src/lib/shift.service.spec.ts
  • Integration test prior art: 
    apps/api-e2e/src/api/shift.spec.ts
  • Seed data and test credentials: unknown
  • Branch convention: 
    feat/<slug>
    off 
    main
  • Commit convention: conventional commits, e.g. 
    feat(ui): users can change their avatar
<!-- archie:facts:end --> 

One line per fact, each command written exactly as it is run, and prior art naming real files whose style new tests should match. **Replace the whole block between the markers**, so hand-written content in `AGENTS.md` survives untouched. No markers means the section does not exist yet: append it at the end, creating the file if the repo has none.

The section is **living**. Any skill that later finds a fact wrong, or creates a gate the repo lacked, writes the correction back in the same run — so re-running this skill is for a genuine change of stack rather than for filling a gap.

If `CLAUDE.md` exists and does not reach `AGENTS.md`, add an `@AGENTS.md` import line to it, so the facts are in context where the user's agent actually reads.
  • Package manager: pnpm
  • Lint: 
    pnpm lint
  • Typecheck: 
    pnpm typecheck
  • Test: 
    pnpm test
  • Build: 
    pnpm build
  • Run the app: 
    pnpm dev
    , served on http://localhost:4200
  • E2E harness: Playwright, specs in 
    apps/web-e2e/src/
  • Unit test prior art: 
    libs/scheduling/src/lib/shift.service.spec.ts
  • Integration test prior art: 
    apps/api-e2e/src/api/shift.spec.ts
  • Seed data and test credentials: unknown
  • Branch convention: 
    feat/<slug>
    off 
    main
  • Commit convention: conventional commits, e.g. 
    feat(ui): users can change their avatar
<!-- archie:facts:end --> 

每项信息占一行，命令需与实际运行时完全一致，参考示例需指定真实文件名，以便新测试匹配其风格。**替换标记之间的整个块**，这样`AGENTS.md`中手动编写的内容不会被改动。若没有标记，则说明该区域不存在：将其追加到文件末尾，若仓库中没有该文件则创建。

该区域是**动态更新的**。后续若有skill发现信息错误，或创建了仓库原本没有的门禁命令，会在运行时直接修正该区域——因此重新运行本skill仅适用于技术栈的真实变更，而非填补信息空白。

若`CLAUDE.md`存在但未关联`AGENTS.md`，需在其中添加`@AGENTS.md`导入行，确保用户的Agent能在上下文环境中读取到这些信息。

4. Keep 
.archie/
committed

4. 确保
.archie/
目录被提交

sh
git check-ignore -v .archie/probe
Silence means the planning tree is already committed. Output names the ignore file, line and pattern that would swallow it: append 
!.archie/
and 
!.archie/**
to that file and re-run until it prints nothing. Planning lives in 
.archie/
and has to survive switching laptops.
When the pattern comes from a global excludes file, report it to the user instead — that file is theirs to change.
sh
git check-ignore -v .archie/probe
无输出表示规划目录已被纳入版本控制。若有输出，则会显示忽略文件、行号以及会排除该目录的规则：需在该文件中追加
!.archie/
和
!.archie/**
，并重新运行命令直至无输出。规划信息存放在
.archie/
目录中，需确保在切换设备时不会丢失。
若规则来自全局排除文件，则需告知用户——该文件由用户自行修改。

5. Report

5. 报告结果

One message: the facts recorded, and each remaining 
unknown
with the skill that will ask for it.
发送一条消息：记录的项目信息，以及每个剩余
unknown
项对应的skill（后续会由该skill询问用户）。