Trellis Instructions

These instructions are for AI assistants working in this project.

This project is managed by Trellis. The working knowledge you need lives under .trellis/:

• .trellis/workflow.md — development phases, when to create tasks, skill routing
• .trellis/spec/ — package- and layer-scoped coding guidelines (read before writing code in a given layer)
• .trellis/workspace/ — per-developer journals and session traces
• .trellis/tasks/ — active and archived tasks (PRDs, research, jsonl context)

If a Trellis command is available on your platform (e.g. /trellis:finish-work, /trellis:continue), prefer it over manual steps. Not every platform exposes every command.

If you're using Codex or another agent-capable tool, additional project-scoped helpers may live in:

• .agents/skills/ — reusable Trellis skills
• .codex/agents/ — optional custom subagents

Managed by Trellis. Edits outside this block are preserved; edits inside may be overwritten by a future trellis update.

项目特定说明（人工维护，不在受管块内）

上面受管块里提到的 .agents/skills/ 是 Trellis 的通用措辞。在本仓库里它的含义 不同，见下。

这个仓库是什么

一个 Claude Code Skills 仓库：自建技能在这里维护并对外分发（npx skills add 装到的就是它们），上游第三方技能只是本地工作区、不在安装面内。

custom/** 的内容会被 custom/daily/skills-sync/ 软链进 ~/.claude/skills， 在使用者的全局 AI 环境里生效。写技能内容时按这个前提对待。

文档语言

中文为主。README.en.md 是英文入口而非全文。

动手前必读

• 改技能（custom/**）→ .trellis/spec/skills/index.md —— frontmatter 契约与内容红线
• 改检查器或 scripts/ → .trellis/spec/checks/index.md —— 退出码语义与分级原则
• 改工作流、发版、PR → .trellis/spec/maintenance/index.md
• 写测试、加检查、判断「验够了没有」→ .trellis/spec/testing/index.md —— 四层测试、验收标准、踩过的坑
• 总导航见 .trellis/spec/index.md

上面这些是「指针」不是「内容」 —— 它们没有被加载进你的上下文（每次会话只加载 本文件与 CLAUDE.md）。所以「知道该读哪个文件」不等于「知道里面写了什么」，动手前 必须真的把对应文件打开。实测过：只凭本文件的指针回答「加一个检查器要接几处」， 答得出「lint.sh 与 ci.yml」，而 spec 里写的是五处 —— 差的正是没打开文件的那部分。

本地检查入口

./scripts/lint.sh          # 19 项静态检查，目标是「本地绿 == CI 绿」
./scripts/lint.sh --list   # 看有哪些检查项

它不覆盖 PR 标题 —— CI 的 commit-messages job 会校验 PR 标题，而标题在 PR 建立 之前不存在。本地全绿不等于 commit-messages 会绿，标题仍需自己按 Conventional Commits 写。

开发流程

本仓库的日常是改技能、改检查器、发版。流程固定，照做即可：

1. 先探测现状 —— 别在不知道当前状态的情况下动手：

   git log --oneline -5 && git status && gh pr list && gh issue list

2. 改之前读对应规范 —— 见上面「动手前必读」那张表。
3. 改完跑静态检查：./scripts/lint.sh，必须全绿。它查不出 PR 标题，标题自己按约定式写。
4. 改了技能内容，再跑行为评测：node scripts/run-evals.js --skill <名字> —— 但要先读下一节，它通过不等于有效。
5. 提 PR：git checkout -b <类型>/<名字> → 提交 → 推送 → gh pr create。 PR 标题按 Conventional Commits 写（squash 合并后，它就是那条提交信息）。
6. CI 全绿再合并：gh pr merge <N> --squash --delete-branch。
7. 发布：把 [Unreleased] 归档成 [X.Y.Z] - 日期 → 单独一个 PR → 合并 → git tag -a vX.Y.Z → git push origin vX.Y.Z。 release.yml 据此生成发布说明。

分工：主会话是调度者与验收者，不自己写实现。 每个任务拆好之后派给子 agent 实现， 主会话负责独立复核（复跑它的验证，不要只读报告）与合并。规则见 .trellis/spec/index.md 的「角色分工」。

下一步做什么，看路线图 Issue —— 那是单一事实来源。 每一轮迭代后由维护者更新它，别在别处另起一份计划。

更完整的方法论（含与具体项目无关的硬规则）见 maintain-loop； 从零把一个裸仓库搭成规范开源项目的六阶段流程见 oss-bootstrap （本仓库已经搭完，日常用不上）。

三层验证，以及「通过不等于有效」

技能「能不能用」分三段，各有一层挡着 —— 但只有第一层是可靠的：

「一个用例通过」不等于「它在测这个技能」。 用 --ablate 复核：只有「装了过、 不装挂」才算数。skills-doctor 的三条用例全绿过，消融一测 0 条有区分度， 已撤掉。触发测试同理：它跑过 15/15，而那份成绩单不含任何信息。

任何新的断言、检查、测试，先证明它能失败 —— 用变异测试把被测对象改坏，看它是否 报红。本仓库反复栽在这上面，例如最近三次：规则 B 的恒真断言、触发测试的 15/15、 skills-doctor 的 3/3。完整记录在 .trellis/spec/skills/index.md。

常见任务从哪开始

RED LINES

• 别删 CLAUDE.md 里的 @AGENTS.md 那一行。 规则只有一份（在 AGENTS.md），而 Claude Code 不会自动读它 —— 靠那一行的导入语法把全文拉进每次会话的上下文。 删了或改成普通链接，规则就静默不再加载：没有报错，只是之后每个会话都不知道规矩。 checks/agent-rules.js 守着这条链
• 不改 .agents/** —— 会被 npx skills update 全量冲掉。上游有问题就记 Issue 或给上游提 PR
• .gitattributes 的规则必须锚定到仓库根。给 .agents/** 设 -text 会关掉 core.autocrlf 的归一化，改动 vendor 文件时出现「整文件都变了」的假 diff
• 检查器一律以 git 索引为目标集，不要改成 find / readdir 递归
• 工作流里 ${{ }} 一律经 env: 中转，不直接写进 run:
• 任何新增检查器都要同时进 lint.sh 的 CHECKS 与 ci.yml 的同名 job —— lint-selftest 会断言两者集合相同

每次编辑中文内容后

python3 -c "
import pathlib
bad=[str(p) for p in pathlib.Path('.').rglob('*') if p.is_file() and '.git' not in p.parts
     and chr(0xfffd) in p.read_text(encoding='utf-8', errors='ignore')]
print(bad if bad else 'OK')
"

写入时混入 U+FFFD 替换字符在本仓库反复出现过，这条不要省。