Skip to content

AGENTS.md

Latest commit

 

History

History
140 lines (99 loc) · 6.69 KB

AGENTS.md

File metadata and controls

140 lines (99 loc) · 6.69 KB
Raw

std-agent 类型速查

本项目的 AI 配置由 stdagent 管理，分为 5 种类型：

  • rules - 自动加载的编码 / 操作规范。AI 在 session 开始就遵守。
  • skills - 按需触发的能力包（遵循 Agent Skills 标准）。AI 看到 description 匹配用户意图时主动调用。
  • commands - 用户输入 /command-name 触发的模板。AI 不主动调用。
  • references - 背景参考资料。AI 仅在需要时查阅，不自动加载。
  • subagents - 隔离子代理定义。AI 通过 spawn 子进程或 CLI 调用执行。

源文件在 .stdai/standards/<type>/<name>.md。用 stdagent which <file> 查文件触发的规则集。用 stdagent explain 查类型详细语义。

std-agent

stdagent 是一个轻量纯 Go CLI 工具：把项目的 AI 配置维护在单一 .stdai/ 目录里，再扩散到 23 个 AI CLI 工具的原生格式（CLAUDE.md / AGENTS.md / .cursor/rules/ / .windsurf/rules/ 等）。本仓库是它的源码仓，同时用 stdagent 管理自己的 AI 助手规则（自举）。

模块结构

cmd/stdagent/                程序入口
internal/
├── cli/                     cobra 命令注册（init / pull / sync / status / clean / budget / intro / upgrade / version / fix）
├── config/                  config.toml 加载
├── parser/                  .md 源文件 + frontmatter 解析
├── source/                  本地 + git 源采集 + .stdaiignore
├── transformer/             23 个 target 各自的转换实现
├── writer/                  原子写盘 + plan + backup
├── runner/                  Sync 编排器
├── state/                   state.json 持久化
├── budget/                  字符/字节预算检查
└── util/                    通用工具
docs/                        spec / architecture / 各 target 调研

技术栈

  • Go 1.26（mise + go + golangci-lint + gofumpt + git-cliff）
  • spf13/cobra（CLI 框架）
  • BurntSushi/toml（config 解析）
  • goccy/go-yaml（frontmatter 解析）
  • bmatcuk/doublestar（glob 匹配）
  • goreleaser（发版）

铁律

  1. 已推送分支禁止改写历史。所有 amend / rebase / reset --hard + force-push 行为只允许在本人独占的 WIP 分支。修补已推送的 commit 用追加新 commit + fast-forward push。
  2. 改 transformer / runner / writer 必带 _test.go。新增 target 至少要有 plan + 关键 fanout 测试，破坏性变更要补充防回归用例。
  3. frontmatter / target 字段不要乱删改，参考 docs/conversion-rules.md 和 docs/format-spec.md 的字段映射矩阵，每条改动都可能影响 23 个 target。
  4. AI 配置维护流程：所有规则源在 .stdai/standards/。改了规则一定要跑 stdagent sync 让产物刷新（CLAUDE.md / AGENTS.md / .claude/rules/ 等），sync 默认会 prune 上次写过但本次不再产出的孤儿文件。
  5. 不要手改 stdagent 生成的根文件（CLAUDE.md / AGENTS.md 等）；改源 .stdai/standards/root.md 或具体 rule 后跑 sync。

维护流程

# 修改 AI 规则（项目说明 / 铁律 / 开发流程）
$EDITOR .stdai/standards/root.md
$EDITOR .stdai/standards/rules/<rule-name>.md
go run ./cmd/stdagent sync           # 用 in-tree 版本验证
go run ./cmd/stdagent status         # 查 drift

# 日常开发
mise run check                       # fmt + lint + test 一键
mise run build                       # 产 bin/stdagent

# 发版（patch / minor）
git tag v0.0.X
git push --tags                      # 触发 goreleaser

commit-style

Conventional Commits 1.0.0 风格

Commit style

Conventional Commits 1.0.0：<type>(scope): <description>

  • type：feat / fix / docs / style / refactor / perf / test / build / ci / chore
  • scope 用模块名（writer / runner / transformer / cli 等），跨多模块的写宽 scope（如 claude-code / release）
  • description 用中文或英文都行，与现有 commit 史保持一致即可
  • 破坏性变更加 !：feat(api)!: 移除旧接口，并在 body 写 BREAKING CHANGE: 段
  • 不要 Co-Authored-By / AI 署名

参考既有提交风格：

fix(writer): 复用 h 变量比较，消除 staticcheck SA4000
refactor(writer): marker 移除 timestamp，输出 deterministic
fix(claude-code): 用 paths 字段而非 applyTo（官方文档要求）
fix(release): ignore CHANGELOG_LATEST.md so goreleaser sees clean tree

.env / 密钥类文件告知用户，不自作主张提交。staged 文件用 git add <file> 显式列出，避免 git add -A 把无关文件带进去。

no-history-rewrite

已推送分支禁止改写历史

已推送分支禁止改写历史

违反任一条立即修复，不辩解。

  • FAIL：已推送分支 git commit --amend + git push --force / --force-with-lease
  • FAIL：已推送分支 git rebase + git push --force / --force-with-lease
  • FAIL：git reset --hard <older> + git push --force 到已推送分支

修补已推送 commit 的唯一方式：追加新 commit + fast-forward push。PR 多一个 commit 不干净也比改写历史好。

唯一例外：本人独占的 WIP 分支，且明确告知协作者后才 amend。main / 受保护分支永远不允许 force-push。

发版相关：tag 一旦 push 到 origin 触发了 goreleaser 也不要删。要修复用更高 patch 版本（v0.0.X+1）覆盖。

test-requirements

改 transformer / runner / writer / parser 必带 _test.go 防回归

测试要求

stdagent 是个"机械扩散器"，bug 修一次要管 23 个 target。任何对 transformer / runner / writer / parser 的改动都必须带测试：

  • 新增 target：至少要有 plan 单测覆盖所有 type（rules / skills / commands / references / subagents）的 fanout 路径。
  • 修 transformer bug：测试要能复现 bug（先红后绿），不能只在原有用例上加断言。
  • 改 runner 控制流（如 prune / dry-run / strict）：单测要覆盖 flag 开/关、第一次/第二次 sync、submodule 边界等行为。
  • 改 writer 落盘逻辑：测试要含 unchanged / overwrite / atomic 三类路径。

跑测试：

go test ./...                          # 全量
go test -race ./internal/runner/...    # race detector，runner 必跑
mise run check                         # fmt + lint + test，提 PR 前必跑

发现已存在的 bug 但你不在改它：要么修，要么开 issue 记录，不要装作没看见。