Aster

Aster 是一个给 AI 用的项目作业本脚手架。

它做的事情很简单：

• 在仓库里放一套固定目录
• 用文件记住“现在要做什么、要遵守什么、做到哪一步了”
• 让 Claude Code 和 Codex 都按同一套规则工作

你可以把它想成：

聊天记录会飘走，文件不会忘。Aster 就是帮 AI 把重要事情写进文件里。

一眼看懂它的结构：

flowchart TB
    U["用户 / 主会话"]
    A["AGENTS.md"]
    R[".aster/<br/>任务、规范、脚本"]
    P{"平台"}
    C["Claude Code"]
    X["Codex"]

    U --> A --> R --> P
    P --> C
    P --> X

    classDef warm fill:#FFF4E8,stroke:#C67A2D,color:#4C2E12,stroke-width:2px;
    classDef mint fill:#EDF8F1,stroke:#3F8F6A,color:#173B2E,stroke-width:2px;
    classDef sky fill:#EEF4FF,stroke:#4C78D0,color:#1D315A,stroke-width:2px;
    classDef plum fill:#F7EEFF,stroke:#8C61C4,color:#44215F,stroke-width:2px;

    class U,A warm;
    class R mint;
    class P plum;
    class C,X sky;

详细说明文档：

• Aster 详细说明文档

适合什么场景

适合：

• 多步骤开发任务
• 希望 AI 记住项目规则
• 希望把任务状态留在仓库里

不太适合：

• 一次性问答
• 只读查询
• 很小的一次性修补

快速开始

最方便的方式是用 npx，不用安装：

Set-Location "D:/Code/your-project"
npx @rooky/aster init --claude --codex

也可以全局安装，然后直接用 aster：

npm install -g @rooky/aster
aster init --claude --codex

如果不传平台参数，默认会同时启用 Claude 和 Codex。

如果目标仓库里已经有 AGENTS.md，Aster 会把自己的受管块插进去或更新已有块。你可以把它想成“往原来的说明书里补一小段固定说明”，不会把整份文件整张擦掉重写。

升级已有项目

第一次接入仓库时用 init；已经接入过的仓库，后续同步模板请用 update：

aster update --dry-run
aster update

如果升级跨度里带有结构迁移，Aster 会明确要求你补上：

aster update --migrate

现在的升级链依赖两个文件：

• .aster/.version：当前仓库安装的模板版本
• .aster/.template-hashes.json：Aster 上次写入模板文件时记录的哈希，用来判断哪些文件是模板原样、哪些文件被你改过

aster --version 会同时显示 CLI 版本和模板版本，例如：

Aster 1.1.0 (template 0.2.0)

挂成全局命令

如果你不想每次都写完整路径，可以先把 aster 挂成全局命令。

最常用的方式是在 Aster 项目目录里执行：

Set-Location "D:/Code/AIProject/other/Aster"
npm link

执行完后，一般就可以直接这样用：

aster --help
aster init --codex
aster update --dry-run

如果你更想走“像安装软件一样安装”的方式，也可以执行：

npm install -g "D:/Code/AIProject/other/Aster"

建议优先用 npm link，因为它更适合本地开发：

• 改完 Aster 代码后，全局命令会直接跟着生效
• 不用每次重新安装

如果执行完还是提示找不到 aster，可以检查 npm 的全局可执行目录：

npm bin -g

然后确认这个目录已经在系统的 PATH 环境变量里。

一个最小使用样例

Set-Location "D:/Code/your-project"
npx @rooky/aster init --claude --codex
python ./.aster/scripts/task.py create "Add payment retry flow" --slug payment-retry
python ./.aster/scripts/task.py start 04-30-payment-retry
python ./.aster/scripts/get_context.py
python ./.aster/scripts/add_session.py --title "initial slice" --summary "Scaffolded the retry workflow"
python ./.aster/scripts/task.py finish

最后一步的 task.py finish 会做两件事：

• 清掉当前任务
• 在 .aster/workspace/handoffs/ 里自动放一份 handoff 小纸条

生成的主要目录

• AGENTS.md
• .aster/
• .claude/
• .codex/
• .agents/skills/

其中：

• .aster/ 是大家共用的工作流核心
• .aster/.version 记录模板版本；.aster/.template-hashes.json 记录模板哈希
• .aster/workspace/ 一开始会有 index.md；记过 session 后会出现 journal-N.md；完成任务后会出现 handoffs/*.md
• .claude/ 是 Claude Code 的接线
• .codex/ 和 .agents/skills/ 是 Codex 的接线

Codex 额外配置

如果你要用 Codex，还要在用户级 ~/.codex/config.toml 里启用 hooks：

[features]
codex_hooks = true

现在已经会做什么

当前版本已经有：

• init
• update
• 模板版本记录（.aster/.version）
• 模板哈希跟踪（.aster/.template-hashes.json）
• legacy 项目升级兼容
• 基础任务管理脚本
• 基础上下文脚本
• 基础 workspace journal / handoff 模板
• Claude hooks / agents / skills
• Codex hooks / agents / skills
• Git commit 提交信息规范 skill
• 基础冒烟测试

当前版本还没有：

• 任务归档
• 子任务系统
• 多开发者 workspace memory