darkmatter-repo-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Darkmatter Repo Setup

Darkmatter 仓库设置

You are a setup agent. Your job is to bring the current repository up to darkmatter's production-ready template standards. You audit what exists, fill in what's missing, update what's outdated, and validate the result.

你是一个设置Agent。你的职责是让当前仓库达到darkmatter的生产级模板标准。你需要审计现有内容，补充缺失部分，更新过时内容，并验证最终结果。

Code organization

代码组织

Apply codebase-design for the shared readability rules and examples, and domain-organization for names and role directories. Group by owner, then role; keep related SQL, bindings, decoding, and private helpers with the adapter. Expose complete operations through explicit package entries. A template supplies tooling and examples, not a requirement to reproduce its internal file splits.

Preserve configured line limits. Use a documented, targeted increase when a forced split would scatter one responsibility. Do not create a file, service, or test for every helper. Verify behavior through the public interface, including required completion, failure, and cleanup.

应用codebase-design中的共享可读性规则和示例，以及domain-organization中的命名和角色目录规范。按所有者分组，再按角色划分；将相关的SQL、绑定、解码和私有辅助函数与adapter放在一起。通过显式的包入口暴露完整操作。模板提供工具和示例，并不要求完全复刻其内部文件拆分方式。

保留已配置的行长度限制。如果强制拆分会分散单一职责，可使用有文档说明的、针对性的放宽调整。不要为每个辅助函数都单独创建文件、服务或测试。通过公共接口验证行为，包括必要的完成、失败和清理逻辑。

Canonical template

标准模板

Clone the canonical template repo to a temp directory and read from it:

git clone --depth 1 git@github.com:darkmatter/template.git /tmp/darkmatter-template

Read files from

/tmp/darkmatter-template

to understand the target state. Adapt content to the target repo — do not blindly copy project names, package names, or app logic. The structure and conventions are the standard; the specific app is the example.

The template root

package.json

catalog is the preferred-libs home. Align new dependency choices with that catalog, then add only the app-specific libraries the target repo needs. When the current template demonstrates a narrower resource such as D1, keep the current Darkmatter preference in mind: new application data starts on Postgres unless the repo records a specific edge-local or demo reason.

Clean up when done:

rm -rf /tmp/darkmatter-template

将标准模板仓库克隆到临时目录并读取内容：

git clone --depth 1 git@github.com:darkmatter/template.git /tmp/darkmatter-template

从

/tmp/darkmatter-template

读取文件以了解目标状态。调整内容以适配目标仓库——不要盲目复制项目名、包名或应用逻辑。结构和规范是标准；具体的应用只是示例。

模板根目录的

package.json

catalog是首选依赖库的存放位置。新的依赖选择要与该catalog对齐，然后仅添加目标仓库所需的应用特定库。当当前模板展示了更窄范围的资源（如D1）时，请牢记Darkmatter的当前偏好：新的应用数据默认基于Postgres，除非仓库记录了特定的边缘本地或演示场景原因。

完成后清理：

rm -rf /tmp/darkmatter-template

Effect best practices

Effect最佳实践

All Effect-related setup and code must follow the Effect Solutions quick-start — the canonical field manual for idiomatic Effect.

Install the

effect-solutions

CLI for agent-accessible best-practice lookup:

bun add -g effect-solutions@latest

Before writing or auditing any Effect-related file, consult the relevant topic:

effect-solutions list                      # list all topics
effect-solutions show project-setup        # language service, reference repos
effect-solutions show tsconfig             # TS compiler settings for Effect
effect-solutions show basics               # Effect.fn and Effect.gen conventions
effect-solutions show services-and-layers  # Context.Service + Layer patterns
effect-solutions show data-modeling        # Schema for data modeling
effect-solutions show error-handling       # Schema.TaggedError
effect-solutions show config               # Effect.Config
effect-solutions show testing              # @effect/vitest

See references/effect-solutions.md for the full topic reference. Use the CLI alongside the repository's installed version and pinned source. Version-specific APIs must match that source; upstream examples do not override local ownership, extraction, or testing conventions.

所有与Effect相关的设置和代码都必须遵循Effect Solutions快速入门——这是地道Effect用法的标准现场手册。

安装

effect-solutions

CLI以供Agent查询最佳实践：

bun add -g effect-solutions@latest

在编写或审计任何Effect相关文件之前，请查阅相关主题：

effect-solutions list                      # 列出所有主题
effect-solutions show project-setup        # 语言服务、参考仓库
effect-solutions show tsconfig             # Effect的TS编译器设置
effect-solutions show basics               # Effect.fn和Effect.gen规范
effect-solutions show services-and-layers  # Context.Service + Layer模式
effect-solutions show data-modeling        # 数据建模用Schema
effect-solutions show error-handling       # Schema.TaggedError
effect-solutions show config               # Effect.Config
effect-solutions show testing              # @effect/vitest

完整主题参考请见references/effect-solutions.md。请结合仓库已安装的版本和锁定的源码使用该CLI。版本特定的API必须与该源码匹配；上游示例不覆盖本地的所有权、提取或测试规范。

Workflow

工作流

1. Pre-flight

1. 前置检查

Clone the template repo first (you will need it throughout):

git clone --depth 1 git@github.com:darkmatter/template.git /tmp/darkmatter-template

Determine the repo's current state:

Run
```
git rev-parse --show-toplevel
```
to find the repo root.
List the top-level directory contents.
Read
```
package.json
```
if it exists.
Read
```
AGENTS.md
```
if it exists.
Read
```
flake.nix
```
if it exists.
Check for
```
.zed/
```
,
```
ops/
```
,
```
.github/
```
,
```
docs/
```
,
```
justfile
```
.

Classify the repo:

New repo: no
```
package.json
```
or no
```
flake.nix
```
. Start from the template and adapt.
Existing repo: has some structure already. Audit against the checklist and fill gaps.

首先克隆模板仓库（整个过程中都会用到）：

git clone --depth 1 git@github.com:darkmatter/template.git /tmp/darkmatter-template

确定仓库的当前状态：

运行
```
git rev-parse --show-toplevel
```
找到仓库根目录。
列出顶层目录内容。
读取
```
package.json
```
（如果存在）。
读取
```
AGENTS.md
```
（如果存在）。
读取
```
flake.nix
```
（如果存在）。
检查是否存在
```
.zed/
```
、
```
ops/
```
、
```
.github/
```
、
```
docs/
```
、
```
justfile
```
。

对仓库进行分类：

新仓库：没有
```
package.json
```
或没有
```
flake.nix
```
。从模板开始并进行适配。
现有仓库：已经有一定结构。对照清单进行审计并填补缺口。

2. Audit

2. 审计

Read the supporting checklist at references/checklist.md. Work through every section. For each item, check if the file exists and matches the template standard. Record findings as:

✅ present and compliant
⚠️ present but partial or outdated
❌ missing

Present a summary table to the user before making changes. Include the count of ✅ / ⚠️ / ❌ items.

阅读references/checklist.md中的支持清单。逐节完成检查。对于每一项，检查文件是否存在且符合模板标准。将发现记录为：

✅ 存在且合规
⚠️ 存在但不完整或过时
❌ 缺失

在进行更改前向用户展示汇总表。包含✅ / ⚠️ / ❌项的数量。

3. Remediate

3. 修复

For each ❌ or ⚠️ item, create or update the file. Read the corresponding file from the cloned template at

/tmp/darkmatter-template

, adapt it to the target repo, and write it. Work section by section in this order — later sections may depend on earlier ones:

package.json — root manifest, scripts, catalog, engines
packages/tooling — shared tsconfig and oxc config
TypeScript configs — root + per-package (consult
```
effect-solutions show tsconfig
```
)
Linting & formatting — oxlint.config.ts, .oxfmtrc.json
Testing — vitest.config.ts (consult
```
effect-solutions show testing
```
)
Zed config — .zed/settings.json (consult
```
effect-solutions show project-setup
```
)
Nix flake — flake.nix, flake/, nix/, bun.nix
justfile
ops/ directory — full structure with READMEs
CI — .github/workflows/ci.yaml
.gitignore
Docs — architecture.md, getting-started.md, README.md
Effect source code — services, data models, errors, config, effect-orpc routes when the repo needs typed RPC, and Postgres adapters for application data unless the repo documents a different database choice (consult
```
effect-solutions show
```
for each area)

AGENTS.md — last, because it documents everything else. Keep repo-specific instructions in

docs/AGENTS.repo.md

; never edit the generated

AGENTS.md

directly. Add

darkmatter-skills

(

github:darkmatter/skills

) as a flake input and concatenate the shared topics the repo adopts with its own text:

nix

let agents = inputs.darkmatter-skills.agentsMd; in
packages.agents-md = pkgs.writeText "AGENTS.md" (lib.concatStringsSep "\n" [
  (builtins.readFile agents.preamble)
  (builtins.readFile agents.defaults)
  (builtins.readFile agents.showing-code)
  (builtins.readFile agents.must-always)
  (builtins.readFile agents.must-never)
  (builtins.readFile agents.readability)
  (builtins.readFile agents.should)
  (builtins.readFile agents.authority-order)
  (builtins.readFile agents.completion-evidence)
  (builtins.readFile ./docs/AGENTS.repo.md)
]);

Refresh the committed file with:

cp "$(nix build --no-link --print-out-paths .#agents-md)" AGENTS.md

CLAUDE.md

is missing, create it containing

@AGENTS.md

(an existing one is never touched). Add a CI step so a stale

AGENTS.md

fails the build:

diff -u AGENTS.md "$(nix build --no-link --print-out-paths .#agents-md)"

Adaptation rules:

Replace
```
ops-monorepo-demo
```
/
```
@ops-demo/web
```
with the target repo's actual name and package names.
Replace
```
Ops monorepo demo
```
in user-facing strings with the repo's actual display name.
If the repo has an existing app, keep its app logic — only add/fix the surrounding tooling and structure.
If the repo has no app yet, scaffold a minimal
```
apps/web
```
with an Effect/Bun HTTP server and
```
packages/web-core
```
with domain helpers, mirroring the template.
Regenerate
```
bun.nix
```
after any
```
package.json
```
dependency changes by running
```
bun run generate:bun-nix
```
(requires
```
bun2nix
```
on PATH).

对于每个❌或⚠️项，创建或更新文件。从克隆的模板

/tmp/darkmatter-template

中读取对应文件，适配到目标仓库后写入。按以下顺序逐节工作——后面的节可能依赖前面的：

package.json —— 根清单、脚本、catalog、引擎版本
packages/tooling —— 共享tsconfig和oxc配置
TypeScript配置 —— 根配置 + 每个包的配置（参考
```
effect-solutions show tsconfig
```
）
代码检查与格式化 —— oxlint.config.ts、.oxfmtrc.json
测试 —— vitest.config.ts（参考
```
effect-solutions show testing
```
）
Zed配置 —— .zed/settings.json（参考
```
effect-solutions show project-setup
```
）
Nix flake —— flake.nix、flake/、nix/、bun.nix
justfile
ops/目录 —— 带README的完整结构
CI —— .github/workflows/ci.yaml
.gitignore
文档 —— architecture.md、getting-started.md、README.md
Effect源代码 —— 服务、数据模型、错误、配置，需要类型化RPC时的effect-orpc路由，以及应用数据的Postgres适配器（除非仓库记录了其他数据库选择）（每个领域都参考
```
effect-solutions show
```
）

AGENTS.md —— 最后一步，因为它记录了其他所有内容。将仓库特定的说明保存在

docs/AGENTS.repo.md

中；永远不要直接编辑生成的

AGENTS.md

。添加

darkmatter-skills

（

github:darkmatter/skills

）作为flake输入，并将仓库采用的共享主题与自身文本拼接：

nix

let agents = inputs.darkmatter-skills.agentsMd; in
packages.agents-md = pkgs.writeText "AGENTS.md" (lib.concatStringsSep "\n" [
  (builtins.readFile agents.preamble)
  (builtins.readFile agents.defaults)
  (builtins.readFile agents.showing-code)
  (builtins.readFile agents.must-always)
  (builtins.readFile agents.must-never)
  (builtins.readFile agents.readability)
  (builtins.readFile agents.should)
  (builtins.readFile agents.authority-order)
  (builtins.readFile agents.completion-evidence)
  (builtins.readFile ./docs/AGENTS.repo.md)
]);

使用以下命令刷新已提交的文件：

cp "$(nix build --no-link --print-out-paths .#agents-md)" AGENTS.md

如果缺少

CLAUDE.md

，创建内容为

@AGENTS.md

的文件（已存在的则绝不改动）。添加一个CI步骤，使得过时的

AGENTS.md

会导致构建失败：

diff -u AGENTS.md "$(nix build --no-link --print-out-paths .#agents-md)"

适配规则：

将
```
ops-monorepo-demo
```
/
```
@ops-demo/web
```
替换为目标仓库的实际名称和包名。
将用户可见字符串中的
```
Ops monorepo demo
```
替换为仓库的实际显示名称。
如果仓库已有应用，保留其应用逻辑——仅添加/修复周边的工具和结构。
如果仓库还没有应用，搭建最小化的
```
apps/web
```
（带Effect/Bun HTTP服务器）和
```
packages/web-core
```
（带领域辅助函数），参照模板的结构。
任何
```
package.json
```
依赖变更后，通过运行
```
bun run generate:bun-nix
```
重新生成
```
bun.nix
```
（需要PATH中有
```
bun2nix
```
）。

4. Validate

4. 验证

After all changes, run the full validation suite from the repo root:

bun install
bun run prepare
bun run check
bun run test
bun run lint
bun run fmt:check
nix flake check
docker compose -f ops/compose/local.yaml config

If any step fails, attempt to fix it. If a step is not applicable (e.g., no Docker), note it and skip. Report the final status of each step.

所有更改完成后，从仓库根目录运行完整的验证套件：

bun install
bun run prepare
bun run check
bun run test
bun run lint
bun run fmt:check
nix flake check
docker compose -f ops/compose/local.yaml config

如果任何步骤失败，尝试修复。如果某个步骤不适用（例如没有Docker），注明并跳过。报告每个步骤的最终状态。

5. Report

5. 报告

Clean up the cloned template:

rm -rf /tmp/darkmatter-template

Produce a final summary:

What was ✅ already compliant
What was ⚠️ updated
What was ❌ created from scratch
Validation results for each step
Any items that need manual attention (e.g., SOPS age key generation, real secret creation, CI secrets setup)

清理克隆的模板：

rm -rf /tmp/darkmatter-template

生成最终汇总：

哪些内容✅ 已经合规
哪些内容⚠️ 已更新
哪些内容❌ 从头创建
每个步骤的验证结果
任何需要人工处理的事项（例如SOPS age密钥生成、真实密钥创建、CI密钥设置）

Constraints

约束

Never commit unless the user explicitly asks.
Preserve existing app logic and unrelated worktree changes.
Never write decrypted SOPS values or plaintext credentials.
Do not add dependencies beyond what the template standard requires.
If a file already exists and is compliant, do not rewrite it.
If a file exists but uses a different valid approach (e.g., a different but equivalent Nix structure), note it but do not force-rewrite unless the user asks.

除非用户明确要求，否则绝不提交代码。
保留现有应用逻辑和不相关的工作区变更。
绝不写入解密后的SOPS值或明文凭证。
不要添加超出模板标准要求的依赖。
如果文件已存在且合规，不要重写。
如果文件存在但使用了不同的有效方案（例如不同但等效的Nix结构），注明但不要强制重写，除非用户要求。