章节 01
导读 / 主楼：astack：为AI编程智能体设计的标准化工作流技能框架
项目背景
随着Claude Code、Codex等AI编程智能体的普及，开发者面临一个新问题：如何让多个智能体在协作时保持一致的工作方式和文档标准？astack项目应运而生，它提供了一套共享的"词汇表"，让不同智能体能够理解并执行标准化的工作流程。
核心概念：工作流即技能
astack将常见开发活动抽象为九个可复用的工作流技能：
九项核心技能
| 技能名称 | 角色描述 |
|---|---|
| astack | 元技能——评估任务规模（小/中/大）并路由到合适的工作流 |
| astack-brainstorm | 编码前的思考与问题分析 |
| astack-plan | 将需求转化为可执行的实现计划 |
| astack-work | 在需求明确后执行实现或调试 |
| astack-review | 对代码、文档或计划进行只读审查 |
| astack-qa | 测试流程、复现bug、按评分标准评估质量 |
| astack-ship | 提交、推送、创建PR、部署 |
| astack-cleanup | 非文档类的结构修复（技能、运行时配置、入口点） |
| astack-compound | 从有意义的工作中提炼持久知识 |
| astack-docs | 初始化/迁移/检查文档树——OpenAI风格布局 |
这种设计让智能体能够"说同一种语言"，无论底层使用哪个模型或工具。
文档结构检查器
astack最具特色的设计是其文档结构检查器。它认识到一个现实问题：当AI负责大部分文档编写时，文档结构容易随时间漂移。检查器通过强制性的文档布局规范来解决这个问题。
强制文档布局
当仓库选择加入（在根目录创建.astack/）时，检查器强制执行以下结构：
AGENTS.md（≤150行，需目录）
ARCHITECTURE.md（顶层系统架构图）
docs/
├── DESIGN.md, FRONTEND.md, PLANS.md, PRODUCT_SENSE.md
├── QUALITY_SCORE.md, RELIABILITY.md, SECURITY.md
├── design-docs/（决策文档，需YAML前置元数据）
│ └── index.md
├── exec-plans/
│ ├── active/（进行中计划）
│ ├── completed/
│ └── tech-debt-tracker.md
├── generated/（自动生成产物）
├── product-specs/
├── references/（外部文档，*-llms.txt格式）
└── _legacy/（迁移期间的临时隔离区）
YAML前置元数据要求
每个设计文档、执行计划和产品规格都必须包含YAML前置元数据：
---
status: stable # draft, active, completed, archived
updated: 2026-04-21
folders: [mobile] # 适用的子项目，或 [all]
---
这种强制规范确保文档的一致性和可追踪性。
安装与使用
安装技能
npx skills add andthezhang/astack
这会将所有astack-*技能安装到智能体技能目录，并在skills-lock.json中记录版本。
仓库初始化
从仓库根目录执行： "为此仓库初始化astack文档"
astack-docs技能会以快照模式运行，扫描现有文档，提出迁移方案，执行移动操作以符合规范布局，并写入.astack/last-sync记录。
Git预提交钩子
项目推荐安装预提交钩子，在提交前自动运行检查器：
LINT_SCRIPT="$HOME/.agents/skills/astack-docs/lint/lint.ts"
cat > .git/hooks/pre-commit << 'HOOK'
#!/bin/sh
# 如果astack未安装则跳过
[ -f "$LINT_SCRIPT" ] || exit 0
exec bun run "$LINT_SCRIPT" "$REPO_ROOT"
HOOK
chmod +x .git/hooks/pre-commit
这种设计确保文档规范在团队协作中得到强制执行。
架构设计哲学
astack的设计理念体现了几个关键原则：
轻量优先
项目刻意保持轻量。工作流技能本质上是"路由散文"——提供判断而非执行。唯一确定性的部分是文档检查器，因为这是唯一需要阻止智能体漂移的环节。
与执行层分离
astack明确区分了"意见层"和"执行层"。如果需要执行密集型技能（真实浏览器自动化、真实部署、真实QA测试），应该使用gstack等执行框架。astack只负责定义工作流程和文档规范。
可选加入
每个仓库独立选择是否加入。这种设计避免了强制推行，让团队根据实际需求决定是否采用。
技术依赖
- Bun ≥ 1.0：用于运行TypeScript检查器
- Git：用于预提交钩子
- 支持SKILL.md的智能体：Claude Code、Codex或类似工具
不需要Node.js编译步骤，检查器是纯TypeScript，Bun可直接运行。
实用价值
astack解决了AI辅助开发中的几个实际问题：
- 标准化协作：多个智能体或人机协作时保持一致的流程
- 文档质量：防止AI生成的文档随时间变得混乱
- 知识沉淀：通过compound技能确保经验被记录和复用
- 渐进采用：可选加入模式降低采纳门槛
对于正在使用AI编程智能体的团队，astack提供了一个可落地的标准化方案，值得评估其适用性。
