scrolls-setup

设置 docs/.scrolls/

docs/.scrolls/ 是一组小型 Markdown 文件，充当项目跨会话的工作记忆：项目的功能、当前状态、已知的缺失项及其原因、接下来要做什么，以及需要避开的陷阱。SCROLLS.md 会引导后续每次会话先查看 docs/.scrolls/STARTER.md，这样就能接续当前状态，而不用每次都从头重新发现；同时提供一个简短的 CLAUDE.md，指向 SCROLLS.md，并提供与之对应的 AGENTS.md，指向 CLAUDE.md，供会读取该文件的运行框架使用。此技能会为尚未设置这套系统的项目搭建相关文件。

此技能自身的 assets/templates/ 目录存放源模板——请从中复制，切勿直接修改这些文件。

跨平台

与另外四个 scrolls 技能不同，此技能没有随附需要二选一的 .sh/.ps1 脚本——这里没有需要移植的内容。文件创建通过你自己的 Read/Write/Edit 工具完成（而非原始 shell 命令）；此技能依赖的唯一外部命令（git rev-parse --show-toplevel）无论从 bash 还是 PowerShell 调用，行为都相同——两者都支持本文件中使用的相同 $(...) 命令替换语法。在 macOS、Linux 和 Windows 上的使用方式一致，无需针对不同环境进行分支处理。

选项

用户可以在 /scrolls-setup 后以纯文本形式传入以下选项，顺序不限——这里没有真正的 argv 解析器，因此请自行读取调用文本并提取选项：

• -p <path> / --path=<path> / --path <path> — 自定义 docs 文件夹。除非指定绝对路径（以 / 开头），否则路径相对于当前工作目录。适用于单体仓库或非标准目录布局，例如，--path=packages/api/docs 会将 scrolls 文件放在 packages/api/docs/.scrolls。这是唯一一个直接指定 docs 文件夹，而非选择基准目录的选项——深入目录时需要权衡，请参阅步骤 4 中关于 SCROLLS.md/CLAUDE.md 放置位置的说明。
• -t / --reporoot — 将所有内容固定在 git 仓库顶层（$(git rev-parse --show-toplevel)），无论实际从哪个子目录调用。如果当前目录不在 git 仓库内，则会清楚地提示失败——因为找不到仓库根目录。
• -l / --local — 明确将所有内容固定在当前工作目录。默认情况下，如果没有指定 -p/-t/-l，就会采用此方式；此选项用于明确指定该方式，例如跳过步骤 1 中的不匹配检查。
• -r / --recurse — 创建任何内容之前，递归扫描 BASE_DIR，检查附近是否已有 scrolls 文件夹（使用 /scrolls-hide//scrolls-unhide 所用的相同范围受限、会排除特定目录且以 STARTER.md 为判定依据的搜索），以免意外创建重复项。继续操作时，此选项不会改变新 scrolls 文件夹的创建位置——请参阅步骤 1。
• -u / --unhide — 将 scrolls 文件夹命名为 scrolls，而非默认的 .scrolls，使其不会被点文件规则隐藏。不指定时采用默认值（隐藏）。

-p、-t 和 -l 是回答同一个问题（“docs 文件夹放在哪里？”）的三种不同方式——最多只能指定一个。如果指定了多个，请停止并询问用户想采用哪种方式。-r 是独立选项，可与上述任一选项（或不指定任何选项）自由组合。

步骤

1. 解析 BASE_DIR，避免覆盖现有工作

计算 BASE_DIR——用于存放 docs 文件夹、SCROLLS.md、CLAUDE.md 和 AGENTS.md 的目录：

• 给定 -t/--reporoot：BASE_DIR = $(git rev-parse --show-toplevel)。如果该命令失败（当前目录不在 Git 仓库中），请停止并告知用户——这里没有可锁定的仓库根目录；建议改用 --path。
• 给定 -l/--local，或给定 -p/--path：直接跳过，继续计算下面的 DOCS_BASE——-l 使用 BASE_DIR = $(pwd)，而 -p 会完全绕过 BASE_DIR（参见 DOCS_BASE 下方的说明）。
• 未给定任何参数（最常见的情况）：BASE_DIR = $(pwd)。但首先，如果当前目录位于 Git 仓库中，请运行 git rev-parse --show-toplevel 并将结果与 $(pwd) 比较。如果两者相同，或当前目录不在 Git 仓库中，则无需提醒。如果不同，请明确告知用户：从这里运行会在 $(pwd)/docs/.scrolls 下创建 scrolls，与仓库根目录（<repo-root>）中可能已有的内容分开，并询问他们的意图——使用当前目录（默认值；如果没有明显偏好，则继续使用该目录），还是改用仓库根目录（等同于重新运行并加上 -t）。不要一直等待用户回复——如果无法确定，优先使用当前工作目录，因为这是该技能文档所述的默认值。

如果给定了 -r/--recurse，请在接触文件系统之前执行以下扫描：在 BASE_DIR 下递归搜索所有包含 STARTER.md 的 .scrolls 或 scrolls 目录（如果给定了 -p，则跳过此步骤——自定义 --path 是用户明确指定的位置，无需质疑），并像 /scrolls-hide//scrolls-unhide 一样排除以下大型或供应商目录：node_modules、.git、vendor、dist、build、.venv、venv、__pycache__、target、.next、.cache；搜索深度应限制在合理范围内（其他 scrolls 技能使用的深度为 8）。如果发现 BASE_DIR 下存在除即将创建的 SCROLLS_PATH 之外的现有 scrolls 文件夹，请告知用户并询问他们是否原本想对该文件夹运行 /scrolls-update，而不是在这里另建一个；只有在用户确认要这样做时，才继续创建（例如，为子项目有意设置独立的 scrolls 系统）。

然后：

DOCS_BASE    = the --path value if -p was given, else "${BASE_DIR}/docs"
SCROLLS_DIR  = "scrolls" if --unhide/-u was passed, else ".scrolls"
SCROLLS_PATH = "${DOCS_BASE}/${SCROLLS_DIR}"

SCROLLS_PATH 将替换下方及模板中所有出现的 docs/.scrolls；本技能的其余部分均泛指“scrolls 路径”。如果用户已经设置了隐藏的 .scrolls，之后又想将其转换为可见形式，这属于单独的专用操作——请引导他们使用 /scrolls-unhide，而不是重新运行本技能。

如果 SCROLLS_PATH 已存在且其中有文件，请停止并询问用户：他们是想只补齐缺失文件，还是保持现状——切勿悄悄覆盖现有 scroll 文件，因为 HANDOFF.md/PLAN.md 等文件可能保存着实际积累的状态。SCROLLS.md、CLAUDE.md 和 AGENTS.md 也同样需要谨慎处理：切勿覆盖现有内容。如果传入了 --unhide，但该位置已经存在 .scrolls 文件夹（反之亦然），不要再创建第二个并行的 scrolls 文件夹——请告知用户并引导他们使用 /scrolls-unhide。

2. 收集足够的项目背景

不要长时间询问用户——最小化设置应当快速完成。花几秒钟尽可能推断出所需信息：

• 项目名称：从 package.json 的 name、pyproject.toml 的 [project].name、Cargo.toml 中获取；如果都没有，则使用目录的基本名称。
• 一句话简介：从同一清单文件的 description 字段或现有 README.md 的第一行获取；也可以省略——它只是锦上添花，并非关键信息。
• 快速了解项目：用一小段话说明项目的实际结构——主要入口、最重要的一两个文件或目录，以及主要语言/技术栈。快速查看仓库根目录和清单文件即可，无需深入审查。如果项目确实是空的（刚创建，还没有代码），就如实说明，不要编造结构。

如果上述信息有任何不明确之处（例如，monorepo 中有多个 package.json），可以只问一个澄清问题——但默认应直接着手，而不是反复追问仓库中已有答案的问题。

3. 创建这七个文件

将 assets/templates/ 中的每个文件复制到磁盘上的 SCROLLS_PATH，并用你在第 2 步收集的信息和上文计算出的值替换 {{PROJECT_NAME}}、{{PROJECT_TAGLINE}}、{{QUICK_ORIENTATION}} 和 {{SCROLLS_PATH}} 占位符。SCROLLS_PATH 是绝对文件系统路径，前提是它来自 -t/-l/默认值（这些都会通过 BASE_DIR 解析，而 BASE_DIR 始终是绝对路径）——用于实际写入文件没有问题，但在模板中替换 {{SCROLLS_PATH}} 的文本并不是同一个字符串：

• -t/-l/默认值（从 BASE_DIR 派生）：替换为 简短 形式 docs/${SCROLLS_DIR}（例如 docs/.scrolls）——绝不要使用绝对路径 SCROLLS_PATH。这样可以确保文件具有可移植性：SCROLLS.md 最终也总是位于 BASE_DIR（第 4 步），因此相对于 BASE_DIR 的引用始终正确，无论 BASE_DIR 是 $(pwd) 还是 Git 根目录，也无论之后由哪台机器或哪个克隆读取。若在此处写入绝对路径，仓库一旦被克隆到其他位置就会失效。
• -p/--path：按原样替换为基于 DOCS_BASE 的完整 SCROLLS_PATH（例如 packages/api/docs/.scrolls）——此路径本身已经是相对路径，而且此情况下 SCROLLS.md 的最终位置取决于具体判断（见第 4 步），因此应保留现有行为，不要自行猜测更短的形式。

模板	→	用途
STARTER.md	SCROLLS_PATH/STARTER.md	阅读顺序 + 何时更新表。每个会话首先阅读的入口文件。
SPEC.md	SCROLLS_PATH/SPEC.md	功能列表，随着功能发布逐步填写。
HANDOFF.md	SCROLLS_PATH/HANDOFF.md	当前状态快照——每个会话都会覆盖，不追加内容。
GAP_ANALYSIS.md	SCROLLS_PATH/GAP_ANALYSIS.md	已知缺失或不完整的内容。
GAP_CONTEXT.md	SCROLLS_PATH/GAP_CONTEXT.md	每项差距存在的原因（有意取舍、疏忽还是阻碍因素）。
PLAN.md	SCROLLS_PATH/PLAN.md	按优先级排序、带工单的待办事项。
WISDOM.md	SCROLLS_PATH/WISDOM.md	约束 / 陷阱 / 难点 / 经验教训部分。

这是最精简的一组——正好包含 STARTER.md 中逐一介绍的六个文件，再加上 STARTER.md 本身。不要预先臆造额外的 scroll 文件（安全审查、架构决策记录、子系统深入分析等）；之后由负责相应工作的人员按照 STARTER.md 最后一节所述的模式，自然地添加这些文件。如果没有找到值得使用的内容，就将 {{PROJECT_TAGLINE}} 留空（直接删除占位符，不要保留字面形式的 {{...}} 文本）；这样写成 You're picking up work on **Foo**.（你将接手 Foo 的工作。）即使没有标语从句也很通顺。

STARTER.md 和 SCROLLS_MD_BLOCK.md 是仅有的包含 {{SCROLLS_PATH}} 的模板——请按上述规则替换（-t/-l/默认值使用简短形式，-p 使用完整的 SCROLLS_PATH），不要使用占位符字符串，并在两个文件中使用 相同 的替换值。CLAUDE_MD_BLOCK.md 和 AGENTS_MD_BLOCK.md 无需进行任何替换——见第 4 步。

模板有意保持接近空白的状态（例如使用“（尚无追踪内容）”之类的占位项目符号）——不要贸然在 SPEC.md 中填入猜测的功能列表，或在 PLAN.md 中编造工单。精简脚手架的作用是搭好 框架；内容会在实际会话中逐步积累。唯一的例外是 STARTER.md 的“快速概览”部分，值得认真填写，因为这是每个会话都会立即依赖的静态背景信息。

4. 将 SCROLLS.md、CLAUDE.md 和 AGENTS.md 指向 STARTER.md

此步骤始终会运行，无论第 1 步对 scrolls 文件夹自身的七个文件作出了什么决定——即使项目原本已有内容完整的 docs/.scrolls/，且该目录未作改动，也仍要在此处检查并补齐 SCROLLS.md/CLAUDE.md/AGENTS.md。这正是此技能可幂等且可安全重复运行的原因：只为补上这条引用链而对现有项目再次运行时（无论运行两次，还是用于由此技能旧版本设置的项目——当时尚无 SCROLLS.md/AGENTS.md），都不会重复或覆盖任何内容——以下三项检查分别是仅在缺失时创建、仅在尚未引用时插入，以及已正确时保持原样。

读取 assets/templates/SCROLLS_MD_BLOCK.md，并像处理 STARTER.md 一样替换其中的 {{SCROLLS_PATH}}——替换后的内容就是要安装为 SCROLLS.md 的内容。

• -t/-l/默认（由 BASE_DIR 推导）：SCROLLS.md（以及下文的 CLAUDE.md、AGENTS.md）放在 BASE_DIR——也就是现在包含 docs 的同一目录。这是固定且明确的：BASE_DIR 正是第 1 步中由 -t/-l/路径不匹配检查确定的目录，因此此处不再需要另行判断“项目根目录”。
• -p/--path：文件应放在哪里确实取决于具体情况，因为自定义的 --path 可能指向一个独立的 monorepo 包（有自己的 SCROLLS.md 和简短的本地引用——类似于先 cd 进入该包再使用 -l 的结果），也可能只是大型仓库的一部分，理应统一由根目录下的一组引用文件指向完整路径。请使用项目其他工具预期的位置；如果确实不明确，请先询问，不要猜测——这是唯一一种猜错代价很高的情况（错误引用会被写入已提交的文档）。

确定文件应放在哪里后：

• 该处还没有 SCROLLS.md：创建一个文件，内容必须与上述内容完全一致。
• SCROLLS.md 已存在，但没有指向 scrolls 路径的引用：在文件顶部附近插入该内容，并与前后内容空行分隔。如果文件一开头已有自己的一级标题，则将此内容的标题作为子标题，而不是再添加一个一级标题 # Scrolls — Project Memory——应遵循现有文件的标题结构，而不是与之冲突。
• SCROLLS.md 已引用 SCROLLS_PATH/STARTER.md（或适用时引用其简写形式）：保持原样；告知用户此情况，不要重复添加该内容块。

然后在同一目录对 CLAUDE.md 执行相同操作。其内容应原样使用 assets/templates/CLAUDE_MD_BLOCK.md——一个固定的两行引用（## Access Scrolls Agentic Memory / See @SCROLLS.md.），而非 SCROLLS.md 的内容本身；无需替换 {{SCROLLS_PATH}}——它始终只引用 SCROLLS.md，而无论使用了哪些标志，两者始终位于同一目录：

• 该处还没有 CLAUDE.md：创建一个文件，内容必须与该内容块完全一致。

• CLAUDE.md 已存在，但尚未引用 SCROLLS.md：在文件顶部附近插入该内容块（放在其他指示之前，因为只有先阅读“请先读此文件”才有效），并与前后内容空行分隔——即使文件已经直接指向 SCROLLS_PATH/STARTER.md 也要插入，这是文件拆分之前遗留的情况。这是一个真实且常见的情况（由此技能 1.2.0 之前的版本设置的项目），也正是此步骤要处理的情况：仍然插入这个简短引用，使 CLAUDE.md 无论原有内容如何，最终都会指向 SCROLLS.md。此操作只会添加内容——绝不删除或改写已有内容，即使因此同一文件中同时存在旧的直接引用和新的简短引用也一样。

• CLAUDE.md 已引用 SCROLLS.md：保持原样；告知用户此情况，不要重复添加。 然后，在同一目录中对 AGENTS.md 执行相同操作——其他一些 Agent 框架（例如 Codex CLI，以及其他遵循 agents.md 规范的框架）会读取它，而不是读取 CLAUDE.md。其内容应与 assets/templates/AGENTS_MD_BLOCK.md 完全一致——一行指向说明（See @CLAUDE.md），而不是 SCROLLS.md 的内容：

• 该目录中还没有 AGENTS.md：创建一个文件，内容严格为这一行。

• AGENTS.md 已存在，但尚未引用 CLAUDE.md：在文件靠上位置插入这一行，并与前后内容以空行分隔，做法与上文相同——不要改动文件中已有的其他内容。

• AGENTS.md 已引用 CLAUDE.md（或已经直接指向 SCROLLS.md/SCROLLS_PATH/STARTER.md）：保持原样；告知用户这一情况，不要重复添加。

5. 汇报结果

总结哪些内容是新建的，哪些内容原本已存在并保持不变——包括 SCROLLS.md、CLAUDE.md 和 AGENTS.md 是新建、更新还是保持原样；并指出接下来最值得用户关注的两三件事：如果你不得不猜测 STARTER.md 中的快速概览段落，应补充完善；某项内容上线后，应编写第一条正式的 SPEC.md 条目。

开发

有关目录布局和版本管理的说明，请参阅 meta/MAINTAINERS.md。执行用户的 /scrolls-setup 请求时不要读取该文件——回答此类请求时，不要对 meta/MAINTAINERS.md 采取任何操作。