SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场agent-spec-tool-first

agent-spec-tool-first

编程与开发

查看项目

更新于 10-16 04:13

技能介绍

用途

agent-spec-tool-first 是一个指导以“工具优先”方式使用 agent-spec CLI 的技能，服务于契约驱动的 AI 编码（contract-driven AI coding）。其核心心智模型是“评审点位移”：传统流程中人类把大部分注意力花在阅读代码 diff 上，而使用 agent-spec 后，人类注意力前移到编写契约（Contract），由机器验证代码是否正确（lifecycle），人类最终做的是“契约验收”而非“代码评审”。

主要能力

技能围绕以下环节组织：

  • 规划：用 contract 渲染任务契约，用 plan 生成计划上下文。
  • 实现：遵循契约中的 Intent、Decisions、Boundaries。
  • 验证：运行 lifecycle / guard 检查代码是否符合规范。
  • 评审：用 explain 生成人类可读摘要，用 stamp 生成 git trailers。
  • 调试：解释验证失败并据此修复代码。

命令速查表涵盖：init（脚手架）、contract（渲染任务契约）、lint（规范质量检查）、plan（生成计划上下文）、lifecycle（完整 lint + verify 流水线）、guard（仓库级检查，用于 pre-commit / CI）、explain（PR 就绪的评审摘要、执行历史）、stamp（预览 git trailers）、graph（依赖图 DOT）、requirements graph --gate（校验 KLL 需求与依赖图）、wiki 系列（status/query/check）、verify（仅原始验证）、checkpoint status（VCS 感知状态）。

Atlas 代码图工作流：build、search、explore、context、flow、impact、affected、status、check、daemon（start/status/service-status/sync/stop），以及 atlas benchmark（validate/plan/summarize/score、agent-plan/agent-gate、serving-plan/serving-gate）和 atlas provider（validate/conformance）。

BDD-spine 命令（0.3.0）：matrix（覆盖矩阵）、promote（将通过的 Rule 提升为能力规范）、audit（规范库健康聚合）、discover（从现有测试反向生成草稿规范）、check-structure（机械分层守卫）、gen-integrations（生成各工具集成文件）。

知识活性层 KLL（0.4.0）：init --workspace（脚手架 knowledge/ 树）、trace（追踪决策/需求到满足它的规范并报告活性）、lint-knowledge（知识语料 lint）、requirements 系列（transition、supersede、status、traceability、graph/plan/work-units/test-obligations、verify-run、compile、bind）。

使用方式

运行任何 agent-spec 命令前，必须先检查 CLI 是否安装：

command -v agent-spec || cargo install agent-spec

若未安装，应告知用户：agent-spec CLI not found. Install with: cargo install agent-spec。

典型 Atlas 工作流示例：

agent-spec atlas build --code . --graph .agent-spec/graph agent-spec atlas search <query> --code . --graph .agent-spec/graph --limit 20 agent-spec atlas explore <query> --profile compact --code . --graph .agent-spec/graph --frozen agent-spec atlas context <query> --profile symbol --code . --graph .agent-spec/graph --frozen agent-spec atlas flow --from <symbol> --to <symbol> --code . --graph .agent-spec/graph --frozen agent-spec atlas impact <symbol> --depth 3 --code . --graph .agent-spec/graph --frozen agent-spec atlas affected --worktree --code . --graph .agent-spec/graph --frozen agent-spec atlas status --code . --graph .agent-spec/graph --format json agent-spec atlas check --code . --graph .agent-spec/graph

适用场景

适用于需要以契约驱动方式让 AI 编码、并希望用机器验证替代人工逐行读 diff 的团队与个人；也适用于需要代码图检索、影响分析、需求追踪、规范库治理、知识活性检查等场景。

限制与注意事项

  • 资料中多处强调：Atlas 图分片、查询索引、绑定属于派生的“工作数据”，不是 KLL 真值；live 状态不能替代图新鲜度、KLL 或 lifecycle 权威。
  • affected 需要显式输入（stdin、staged、worktree 或 commit-range），报告的是图证据，不是推断出的测试；不得从 affected 文件名推断测试。
  • MCP 使用冻结的只读 Atlas 读取；默认工具列表省略 atlas_search，需设置 AGENT_SPEC_MCP_ATLAS_SEARCH=1 才列出；atlas_explore 需 AGENT_SPEC_MCP_ATLAS_EXPLORE=1；atlas_context 需 AGENT_SPEC_MCP_ATLAS_CONTEXT=1，其并发路由还需 AGENT_SPEC_MCP_ATLAS_QUERY_MODE=worker。
  • D4 查询 worker 是可选原型，默认、CI 和单 Agent 场景应保持 direct 模式。
  • 外部 Code Graph provider 需先运行 atlas provider validate，集成前运行 conformance；fixture 通过不等于 F2 语言支持或自动启用许可。
  • 版本信息：技能版本 3.7.1，最后更新 2026-08-14，跟踪 agent-spec 1.4.0；BDD-spine 命令标注 0.3.0，KLL 标注 0.4.0。
  • 资料未提供收费、价格、平台支持范围等信息，暂未提供。