Agent Build Guard

The compiler for the agent codebase you already have.

For AI agents

Use Agent Build Guard when the user asks you to:

• inspect or understand an unfamiliar AI agent codebase;
• trace supported Prompt → Model Call → Schema → Tool/MCP → Consumer relationships;
• detect Prompt-input, output-Schema, or direct-consumer drift before release;
• produce source-mapped diagnostics or a dependency graph without executing or modifying the target repository.

Do not use it to claim Prompt quality, factual correctness, framework-specific workflow semantics, runtime deployment availability, or final values assembled dynamically at runtime.

Start with the canonical Agent Skill. Check the exact machine-readable capabilities, detailed capability matrix, and Agent routing examples before making claims. From a source checkout, run ./scripts/agent-build check --project /absolute/path/to/target; use --format json for machine-readable diagnostics.

Your agent passed CI. It is still broken.

A familiar change lands on Friday:

`evidence` was renamed to `evidencePack` in application code.

The prompt still references {{evidence}}.
The output schema now requires citations[], but no instruction produces it.
The primary model supports structured output; the fallback does not.
The MCP tool exists locally, but is missing in production.
The component is declared read-only, but a reachable tool can write.
The prompt still carries old instructions that no output field or consumer uses.
Every request pays for duplicated context that may distract the model.
An AI-generated prompt was "upgraded" in one pass and silently changed names,
constraints, and assumptions that application code still depends on.
The runtime trace cannot prove which prompt version actually ran.

Version 0.1 catches the implemented Prompt, Schema, call-site, consumer, Sidecar, supported Tool-use, and MCP-operation subset of these failures. It discovers supported Tool and MCP relationships in source; it does not yet prove cross-environment availability. Permission, model/fallback, pipeline, runtime-trace, and semantic Prompt-waste checks remain roadmap work. The capability table is authoritative.

The code type-checks. Each configuration file looks reasonable. The failure lives between them, so someone has to search the repository, reconstruct the flow, and hope nothing was missed.

This project starts where ordinary type checking stops.

Your agent application already has contracts. They are just scattered across prompts, schemas, tools, MCP servers, skills, model routes, permissions, pipelines, and the code that consumes model output.

Everything works—until one field is renamed, a fallback model loses structured output, a tool gains write access, or production runs a prompt different from the one you reviewed.

This is increasingly common because prompts are often generated, expanded, or rewritten by AI too. AI makes prompt changes cheap, but it also makes large, plausible-looking changes easy to accept without noticing contract drift. An upgrade may preserve the general meaning while deleting a required instruction, renaming an output concept, duplicating context, retaining obsolete prose, or changing the relationship between Prompt, Schema, and consumer code.

The compiler can flag the parts of that drift supported by structural evidence. Whether the new wording actually improves model behavior is a separate evaluation question, not a compile-time claim.

Agent Build Guard turns those hidden relationships into a source-mapped Agent IR, links the supported parts of the system, and reports proven failures and explicit analysis gaps before deployment.

Do not rewrite your agent. Make it inspectable.

Abilities / 能力 · English · 中文 · Architecture · Roadmap

[!IMPORTANT] Version 0.1 is an implemented vertical-slice prototype, not a stable API. It supports native and framework-independent Markdown contracts, YAML sidecars, JSON Schema, selected TypeScript/Zod patterns, deterministic artifacts, and a local read-only graph UI. Framework-specific workflow semantics are explicitly not supported without a dedicated adapter.

Read this before analyzing a project

The default analyzer does not use an LLM. It deterministically reads static repository artifacts—not executable code alone—including TypeScript/JavaScript, Markdown prompts, YAML contracts, JSON Schema, sidecars, and dependency manifests. It does not execute the target project, install its dependencies, write into it, or access the network.

Static evidence can prove supported Prompt → LLM Call → Schema → Output Field → Consumer relationships. It cannot safely invent runtime-selected builders, dynamically assembled values, prompt intent, or model quality. Those remain explicit coverage gaps that may later be supplied by a contract, a runtime trace, or an optional LLM migration assistant. LLM suggestions never become authoritative until the deterministic compiler validates them.

Version 0.1 is native-first and framework-independent. If a known framework dependency is detected, generic analysis continues, but framework-specific workflow, state, routing, and runtime semantics are not analyzed. The compiler emits AB1903, and the manifest records semantics: "not-analyzed". Detection does not mean adapter support.

0.1 workflow

The source-checkout experience uses one repository script rather than npx:

# one-time project setup
npm install

# repeatable local commands
./scripts/agent-build check
./scripts/agent-build build
./scripts/agent-build ui

After the package is published to npm, a global installation exposes the same CLI as agent-build:

npm install --global agent-build-guard
agent-build check --project /path/to/your-agent

Human-readable check output ends with the exact command for opening the same project in the interactive UI. build also prints a clickable file:// URL for its generated report. JSON output remains pure machine-readable data for CI and scripts.

The wrapper validates prerequisites before running and prints an actionable error when the supported JavaScript runtime or local dependencies are missing. Parser, schema, graph, and UI libraries are project dependencies installed together; users do not install each analyzer separately.

Analyzed repositories may need their own dependencies installed when a frontend requires full symbol resolution. Basic file, native-contract, sidecar, Markdown, YAML, and JSON Schema inspection should work without building or running the target application.

The default check path requires no LLM credentials, model provider, or network access. A later packaged binary or installer may remove the JavaScript toolchain prerequisite for end users.

“No LLM” does not mean “executable code is the only input.” The deterministic analyzer reads static repository artifacts: TypeScript/JavaScript, Markdown prompts, YAML contracts, JSON Schema, sidecars, and dependency manifests. It proves only relationships supported by those sources. Dynamic dispatch or runtime-built prompts remain visible coverage gaps instead of being guessed. An optional migration assistant may later propose missing contracts, but its output never becomes authoritative until deterministic compilation validates it.

Why this exists

Agent failures often happen between individually reasonable components:

prompt asks for a field       application forgot to provide it
schema requires a property    instructions never ask for it
tool is available             permission contract forbids its effect
primary model works           fallback lacks the required capability
workflow looks connected      one branch never produces required state
reviewed source is correct    production assembled something different

Type checkers see code. Schema validators see values. Agent frameworks see their own runtime. MCP describes protocol-level capabilities. None of them necessarily sees the complete application contract.

Agent Build Guard is the missing linking layer.

Version 0.1 implements the Prompt, Schema, call-site, direct-consumer, and Sidecar portion of that layer. The broader joins above remain explicit roadmap items.

Who it is for

Typical situations

Use Agent Build Guard when:

• you changed a Prompt, Schema, or result field and need to trace the call sites and downstream consumers the static analyzer can currently identify;
• prompts are loaded, rendered, wrapped, or assembled across files and code review no longer reveals the complete path;
• an old repository works in production, but nobody can confidently explain which Prompt and Schema reach each LLM call;
• a vibe-coded prototype has grown into a real product and its implicit cross-file assumptions are becoming risky;
• AI generated or upgraded a large Prompt and you need to know whether required inputs, outputs, constraints, and downstream assumptions drifted;
• you want a deterministic CI check and a visual dependency report without executing or modifying the target project;
• static analysis cannot resolve a dynamic Builder or Schema and you need the gap stated explicitly instead of receiving an AI guess;
• a repository contains a known Agent framework and you need framework-independent coverage while clearly seeing that framework-specific semantics remain unsupported.

Developers who should try 0.1 now

• Agent application developers using TypeScript or JavaScript with Markdown prompts, Zod, JSON Schema, or YAML sidecars.
• Maintainers of existing Agent products who need source-preserving inspection before changing mature Prompt pipelines.
• Vibe-coding and solo developers who want the project structure explained before hidden assumptions become permanent debt.
• Platform and developer-experience engineers evaluating a deterministic local or CI inspection layer for multiple repositories.
• Reviewers and technical leads who need a source-mapped graph and explicit coverage boundaries instead of manually reconstructing the system.

Python AST and framework-specific adapters are not part of 0.1. Python dependency manifests can identify a known framework boundary, but Python source semantics are not yet compiled.

Mature agent systems

Large repositories accumulate stable but implicit behavior. Teams need source-preserving discovery, change-impact analysis, permission review, build/runtime conformance, and gradual sidecar adoption without rewriting prompts that already work.

New and vibe-coded projects

Fast-generated projects accumulate cross-file assumptions before their authors know which contracts to declare. They need a near-zero-configuration advisory check that reveals the real flow, explains broken joins in plain language, and can generate candidate contracts before accidental structure becomes permanent debt.

The engine is shared; the experience is different:

mature project  -> preserve source, recover contracts, control change
new project     -> discover structure early, explain risk, prevent drift

New users should not have to understand Agent IR or write extensive sidecars before receiving value. Automatic discovery comes first; explicit contracts progressively strengthen guarantees.

v0.1 ability matrix

Version 0.1 is best suited to TypeScript or JavaScript Agent projects whose Prompt and Schema relationships are static enough to prove from source. Markdown Prompts, Zod or JSON Schema outputs, and optional YAML Sidecars are the strongest current path.

Supported in v0.1

| Area | Current ability | | --- | --- | | Project sources | Read selected TypeScript/JavaScript, Markdown, YAML, JSON Schema, and root dependency manifests without executing the target | | Markdown Prompts | Parse ordinary Prompt Markdown, template variables, and source locations | | Native Prompt Contract v0.1 | Validate the stable agent-build/[email protected] input/output Frontmatter against a published Schema; small/new projects can require it in agent.build.yaml without allowing source writes | | Prompt file loading | Resolve Markdown ?raw imports and supported static readFileSync paths using string paths, process.cwd(), import.meta.url, new URL, and static path.join/path.resolve | | Prompts written in code | Link direct strings, module/local constants, template strings, string concatenation, literal-array .join(), and bounded local Builders to supported LLM calls | | Prompt rendering | Analyze selected renderPrompt and renderPromptWithBudget flows, including missing and stale input values | | LLM calls and wrappers | Analyze callLLMForTask and bounded local wrappers whose Prompt parameter and fixed Schema can be proven | | Provider SDK calls | Recognize import-proven selected OpenAI, Azure OpenAI, Anthropic, Google GenAI, Vertex AI, Mistral, Cohere, and Vercel AI SDK operations and trace supported Prompt-bearing arguments backward | | Tool discovery | Discover supported Vercel AI SDK tool() / dynamicTool() and inline Tool declarations, and link supported model calls with uses_tool | | MCP discovery | Discover import-proven selected MCP Client/Server registration, connection, discovery, and invocation operations without claiming remote availability | | Output Schemas | Parse JSON Schema object shapes, direct/nested Zod objects, optional fields, real local imports, and bounded local/imported Schema factories | | Downstream consumers | Link direct result.field reads to proven output fields and report consumer/Schema drift | | Existing projects | Bind source files, symbols, fingerprints, and Schemas with generic YAML Sidecars without rewriting mature Prompt prose | | Agent IR and diagnostics | Emit source-mapped nodes, edges, evidence classes, stable hashes, Text/JSON diagnostics, and explicit coverage gaps | | CLI and UI | Run deterministic check/build, generate JSON and static HTML artifacts, and serve a localhost-only read-only UI in English, Simplified Chinese, Spanish, and Japanese | | Safety boundary | Do not execute target code, install target dependencies, call an LLM, access the network, or write inside an external target repository | | Framework boundary detection | Detect LangGraph, CrewAI, OpenAI Agents SDK, Google ADK, AutoGen, Pydantic AI, Semantic Kernel, Mastra, and LlamaIndex dependencies and emit AB1903 |

Partially supported in v0.1

| Area | Exact boundary | | --- | --- | | TypeScript/JavaScript AST | Selected syntax and bounded local dataflow only; no complete TypeScript type-checker or whole-program symbol resolution | | Code-defined Prompt values | Static source shape and interpolation slots are proven; final runtime interpolation values are not known | | Prompt Builders | Supported only when the returned string shape is directly visible as a literal, template, concatenation, literal-array .join(), or supported renderer flow | | Schema factories | Supported for bounded direct returns, wrappers, imports, and selected base-Schema refinements; computed keys and runtime-selected members remain unresolved | | Known Agent frameworks | Generic supported files are still analyzed, but framework workflow, state, routing, and runtime semantics are not interpreted |

Not supported in v0.1

• Python source AST or Python Prompt/Schema dataflow; Python manifests are used only for framework-boundary detection.
• Arbitrary provider SDK call shapes; an unrecognized OpenAI, Anthropic, Gemini, or framework call requires a dedicated analyzer adapter or a supported local wrapper pattern.
• Runtime-selected Builder registries, reflection, plugin dispatch, data-dependent branches, dynamic imports, or Prompts loaded from databases, networks, and configuration services.
• Fully computed Schema keys or runtime-selected Schema members.
• Framework-specific graph semantics, including LangGraph nodes, state, edges, routing, and equivalent concepts in other frameworks.
• Proof that Prompt prose is good, relevant, non-duplicated, factually correct, or responsible for a particular output field.
• Automatic rewriting or deletion of mature Prompt prose.

Unsupported relationships remain visible as coverage gaps instead of being guessed: AB1901 for unresolved Prompts, AB1902 for dynamic Schemas, and AB1903 for detected-but-unanalyzed framework semantics.

Future roadmap—not v0.1 claims

| Planned ability | v0.1 status | | --- | --- | | Cross-environment Tool and MCP availability | Not implemented; source discovery is implemented, deployment and reachability checks are not | | Permission and effect reachability | Not implemented | | Pipeline branch and Artifact checks | Not implemented | | Model and Fallback compatibility | Not implemented | | Context and Token budgeting | Not implemented | | Runtime Trace conformance | Not implemented | | Python AST and framework adapters | Not implemented | | SARIF and editor integration | Not implemented | | Optional LLM migration assistant | Not implemented; suggestions will remain non-authoritative | | Prompt-span semantic lineage, conflict detection, and evaluation-backed ablation | Not implemented |

Implemented diagnostics

These checks are implemented in the deterministic compiler now:

| Implemented check | Example diagnostic | | --- | --- | | Undeclared Prompt variable | {{audience}} is referenced but absent from the native input contract | | Declared but unused Prompt input | staleValue is declared but never referenced in the template | | Missing renderPrompt input | a call does not supply required input audience | | Stale supplied Prompt input | a call supplies legacyContext, but the Prompt no longer references it | | Static code Prompt path | a direct literal, constant, template, concatenation, literal-array .join(), or bounded local Builder is linked to its LLM call | | Unresolved output Schema | a native or Sidecar output binding cannot find its Schema | | Output/consumer drift | code reads result.citations, but the proven Schema has no citations field | | Sidecar source drift | a bound file, symbol, or source fingerprint no longer matches | | Static coverage boundary | a dynamic Prompt, Schema, or known framework semantic cannot be proven | | Invalid required Native Contract | a Prompt is missing agent-build/[email protected], contains an unknown field, or declares an invalid input/output type |

A diagnostic looks like this:

error[AB1003]: prompt requires input `audience`, but this renderPrompt call does not supply it
  --> prompts/summarize.prompt.md:18:1

contract:
  summarizeDocument.inputs.audience: string

help:
  connect an upstream artifact or declare the input optional

Every diagnostic should identify the source location, violated contract, evidence, and remediation path.

Not another agent runtime

Agent Build Guard does not orchestrate your agent, proxy model calls, or require a new framework.

Your existing application ----------------------> existing runtime
        |
        +-- read-only frontends / sidecars
                         |
                         v
                      Agent IR
                         |
          linker -> analysis passes -> artifacts

The default adoption path is sidecar and non-invasive:

1. Inspect — read the repository and report what can be proven. No source changes.
2. Describe — add sidecar contracts for relationships the frontend cannot recover.
3. Validate — run deterministic checks locally or in CI.
4. Instrument (planned) — optionally attach build identities to runtime traces.
5. Migrate — opt in to native contracts or source changes only where they are valuable.

Removing Agent Build Guard from CI should not change how the application runs. Runtime instrumentation is optional and explicit.

Product architecture: implemented core and planned expansion

The long-term compilation unit is the connected agent system, not prompt text alone:

Prompt + Skill + Schema + Tool + MCP + Model + Memory
       + Permission + Pipeline + Artifact + Consumer
                              |
                           Frontends
                              |
                           Agent IR
                              |
         Parse -> Link -> Type -> Effect -> Budget -> Policy
                              |
      Diagnostics / graph / manifest / impact report / eval plan
                         / trace contract

Framework-specific interpretation belongs in frontends. Shared checks operate on Agent IR.

Version 0.1 currently lowers Prompt, Schema, LLM-call, selected Tool and MCP, output-field, consumer, source, and detected-framework-boundary evidence. Model, memory, permission, pipeline, effect, budget, policy, cross-environment availability, and trace passes in the diagram remain planned.

Native-first framework boundary in 0.1

Version 0.1 targets native and framework-independent agent projects. It can detect known framework dependencies such as LangGraph, CrewAI, OpenAI Agents SDK, Google ADK, AutoGen, Pydantic AI, Semantic Kernel, Mastra, and LlamaIndex. Detection is not adapter support: the compiler continues generic static analysis and emits AB1903, while the manifest records each detected framework as semantics: "not-analyzed".

We will claim framework support only when a dedicated adapter lowers that framework's workflow semantics into Agent IR. Those adapters belong in explicit modules or packages—not in permanent product branches and not in the shared compiler core.

Deterministic core, optional AI assistance

The project contains two separate product boundaries.

Deterministic build system

Structured parsers use ASTs, symbols, schemas, configuration, native contracts, and sidecars to build a reproducible graph. Implemented parsing, linking, Schema checks, diagnostics, and build identity produce the same result for the same input. Future permission and policy passes must preserve that same deterministic guarantee.

The trusted check path requires no LLM and no network access.

Optional migration assistant

Mature repositories contain dynamic prompt assembly, implicit naming conventions, and relationships that syntax alone cannot recover. An optional assistant may inspect bounded gaps and propose:

• component identities;
• producer-consumer relationships;
• sidecar contracts;
• prompt-span-to-output-field links;
• semantic conflict warnings;
• evaluation requirements.

AI output is never authoritative. It is a candidate that must be accepted where necessary and recompiled by the deterministic core.

AI proposes. The compiler proves. Humans resolve the remaining ambiguity.

One portable skill, not vendor-specific forks

Version 0.1 includes one canonical inspection skill conforming to the open Agent Skills specification:

agent-build/
  SKILL.md
  scripts/
  references/
  assets/

There is no separate Codex skill, Claude skill, or provider-specific copy. A compatible host reads the same SKILL.md and invokes the same compiler CLI or machine-readable interface.

Host differences must stay outside the canonical skill:

• the compiler exposes portable CLI and JSON contracts;
• optional host adapters translate tool invocation without changing workflow semantics;
• unsupported experimental metadata must not be required for correctness;
• provider-specific instructions must not be copied into the canonical skill;
• conformance fixtures verify that different hosts reach the same deterministic compiler result.

The current skill invokes the deterministic inspection workflow; it is not an implemented LLM migration assistant. A future optional assistant must extend the same portable package rather than creating provider-specific forks. The compiler remains the source of truth.

Evidence, not confidence theater

Every non-trivial relationship carries its provenance:

| Evidence class | Meaning | | --- | --- | | proven | Derived deterministically from syntax, contracts, symbols, or schemas | | observed | Captured in a particular instrumented runtime execution | | inferred | Proposed by a heuristic or LLM and still requires confirmation or evaluation |

An inference score never becomes a proof merely by crossing a threshold.

Roadmap: field-level semantic lineage

Component graphs are useful. Field-level lineage makes them actionable:

Input evidence
   -> Prompt span: "List unresolved uncertainties separately"
   -> Summary.uncertainties[]
   -> JSON Schema constraint
   -> warning panel consumer
   -> uncertainty-recall evaluation

This future layer is intended to answer questions such as:

• Which instruction is supposed to produce this output field?
• Which inputs supply that field?
• Which downstream code consumes it?
• What changes if this sentence is edited?
• Does the field have a schema but no supporting instruction?
• Does an instruction have no observable output target?
• Which prompt spans are duplicated, unreachable, or unrelated to any declared output or policy?
• Which suspected dead spans should be tested through an ablation eval before removal?
• Which claims require runtime evaluation rather than static analysis?

Version 0.1 already represents Schema fields and direct code consumers, but it does not automatically map ordinary Prompt sentences to output fields. Future explicit bindings can be proven; natural-language influence must remain inferred unless stronger evidence validates it. See Evidence and Field Lineage.

Roadmap: Prompt waste analysis

Version 0.1 detects unused template inputs and unresolved Prompt assembly paths. Duplicate-fragment detection, unreachable Prompt spans, semantic staleness, conflict analysis, and Prompt-to-field relevance are planned rather than implemented. A future heuristic or optional assistant may flag suspicious instructions, but those findings must be labeled inferred.

Semantic deadness is not a static fact. Before removing mature prompt prose, the tool should generate an ablation plan that compares quality, safety, latency, and token cost with and without the suspected span. Removal remains opt-in and requires a diff and evaluation evidence.

Why best practices are not enough

Modern frameworks and protocols solve important local problems:

• graph frameworks model nodes, edges, and shared state;
• typed outputs validate model responses;
• tool and MCP schemas validate individual calls;
• guardrails check selected runtime inputs, outputs, or tool calls;
• skills package reusable instructions and resources;
• tracing records what happened after execution.

Those controls are necessary, but they live at different boundaries. A project can follow all of them and still fail at the joins: prompt-to-schema, schema-to-consumer, skill-to-host, tool-to-permission, primary-to-fallback, source-to-runtime, or trace-to-reviewed-build.

Agent Build Guard does not replace these practices. It links them.

This boundary is visible in today's ecosystem: LangGraph compilation performs graph-structure checks inside a LangGraph application; MCP standardizes individual tool schemas and explicitly treats tool annotations as untrusted hints; Agent Skills defines a portable skill package while allowed-tools remains experimental; runtime SDK guardrails execute at specific input, output, or tool boundaries; and GitHub Agentic Workflows demonstrates compile-time hardening inside the GitHub Actions domain. These are strong building blocks, not a whole-application linker across all of them.

References: LangGraph Graph API · MCP Tools · Agent Skills specification · OpenAI Agents SDK guardrails · GitHub Agentic Workflows compilation

Adoption modes

Existing projects: source-preserving overlay

Keep mature prompts and agent code unchanged. Frontends and sidecar contracts bind existing files and symbols to Agent IR identities, retain source maps, and record fingerprints for drift detection.

id: summarizeDocument
source:
  file: src/prompts/summarize.ts
  export: summarizePrompt
inputs:
  document: string
  audience: string
outputSchema:
  file: src/schemas/summary.ts
  export: SummarySchema
effects:
  network: false
  tools: []

New projects: native-first contracts

Small and new projects can require the implemented agent-build/[email protected] standard in agent.build.yaml:

standards:
  promptContract: agent-build/[email protected]

Each Prompt then declares only the v0.1 fields the compiler really validates: contract, id, version, inputs, and output. The published JSON Schema defines the same boundary. Prompt prose remains ordinary Markdown, and Agent Build Guard never initializes the project or writes the Contract for the user.

Outputs

The compiler emits derived artifacts, not a second source of truth. Version 0.1 writes the first four files; the remaining contracts are planned:

.agent-build/
  manifest.json
  graph.json
  diagnostics.json
  report.html
  impact-report.json   # planned
  eval-plan.json       # planned
  trace-contract.json  # planned

Diagnostics should also support human-readable output, JSON, and SARIF for CI and code-scanning integrations.

What this project will not claim

• It cannot prove that an LLM response is factually correct.
• It cannot prove that a prompt is well written or improves task quality.
• It does not silently rewrite mature prompt prose.
• It does not make LLM-generated migration output authoritative.
• It does not replace runtime sandboxing, guardrails, evaluation, or human judgment.
• It does not standardize every framework or force one universal DSL.

Structural correctness is compiled. Semantic claims become explicit evaluation requirements.

Implemented 0.1 scope

The first vertical slice is deliberately narrow:

1. parse native Markdown prompt contracts and generic YAML sidecars;
2. lower native, sidecar, JSON Schema, TypeScript, and direct Zod sources into one Agent IR;
3. link raw Markdown imports, statically resolvable readFileSync loaders, direct literals, module/local Prompt constants, templates, string concatenation, literal-array .join(), bounded local Prompt/LLM wrappers, budget renderers, callLLMForTask, recognized OpenAI/Azure OpenAI/Anthropic/Google GenAI/Vertex AI/Mistral/Cohere Client calls, Vercel AI SDK function calls, Tool definitions and uses, MCP registrations and calls, import-bound Zod outputs, Schema parsers, resolvable Schema factories, and direct consumer field reads;
4. emit source-mapped deterministic diagnostics, stable contract hashes, JSON artifacts, and a static HTML report;
5. serve a fresh light, card-based, localhost-only analysis workspace with English, Simplified Chinese, Spanish, and Japanese locales, a data-backed narrative summary, dependency paths, evidence inspection, search, and diagnostics;
6. reject artifact output paths located inside an external target repository;
7. expose the same CLI through one standards-conforming Agent Skill.

The TypeScript frontend resolves only syntax-proven imports and bounded local dataflow. Its SDK-anchor discovery path requires an imported supported Client or function and a recognized operation; a coincidentally named .create() or generateText() is not enough. It traces static input, instructions, system, message(s), content(s), parts, and text values backward into Prompt nodes. Exact findings deduplicate by stable source identity and graph relation, not by display name, so two genuinely separate same-named Tools remain separate while one AST component reached by several discovery paths remains one node. For code-defined Prompts, it can prove static source shape and interpolation slots—not the final runtime values inserted into those slots. Runtime-selected Builders emit AB1901; dynamic Schemas emit AB1902. Computed dispatch, full TypeScript symbol resolution, Python AST, framework adapters, generic HTTP inference calls, runtime instrumentation, field-level semantic inference, and LLM-assisted migration remain future work. Known framework dependencies are reported as an explicit unsupported semantic boundary rather than silently treated as native coverage. See the Capability Matrix for the exact boundary.

Repository map

• Product thesis
• Architecture
• Native contracts
• Migration strategy
• Roadmap
• Research landscape
• Architectural decisions
• Evidence and field lineage
• Capability matrix
• Agent discovery and evaluation
• Machine-readable capabilities
• LLM documentation index
• Native example
• Sidecar example

Principles

Native-first. Adapter-friendly. Source-preserving.
Deterministic at the core. Evidence on every edge.
LLM-assisted only where semantic inference is necessary.

中文说明

给已经能跑、但越来越难维护的 Agent 工程补上编译期秩序

给 AI Agent 的使用判断

当用户要求理解陌生 Agent 代码库、追踪受支持的 Prompt → Model Call → Schema → Tool/MCP → Consumer 关系、检查发布前合同漂移，或者在不运行和不修改目标项目的情况下生成依赖图时，应使用 Agent Build Guard。

不要用它声称 Prompt 质量、事实正确性、框架专属工作流语义、运行时部署可用性，或动态拼装后的最终值。开始前读取标准 Agent Skill，并以机器可读能力清单、详细能力矩阵和 Agent 路由示例为边界。从源码仓库运行 ./scripts/agent-build check --project /目标项目绝对路径；需要机器读取时添加 --format json。

CI 已经通过，Agent 还是坏了

一个周五提交的普通改动：

业务代码把 `evidence` 改名成了 `evidencePack`。

Prompt 仍然引用 {{evidence}}。
输出 Schema 新增了必填 citations[]，但没有指令要求模型生成。
主模型支持结构化输出，Fallback 却不支持。
MCP Tool 在本地存在，生产环境却没有配置。
组件声明为只读，但它能够到达一个写入 Tool。
Prompt 还保留着没有输出字段或下游消费者需要的旧指令。
每次请求都在为重复上下文付费，还可能分散模型注意力。
Runtime Trace 无法证明生产环境究竟执行了哪个 Prompt 版本。

0.1 能够发现其中已经实现的 Prompt、Schema、调用位置、消费者、Sidecar、受支持 Tool 使用和 MCP 操作。它能发现源码关系，但还不能证明 Tool 或 MCP 在不同部署环境中的真实可用性。权限、模型/Fallback、Pipeline、Runtime Trace 和 Prompt 语义冗余检查仍是路线图。请以能力列表为准。

代码类型检查能够通过，每个配置文件单独看也都合理。错误藏在它们之间，只能依靠人重新搜索整个仓库、恢复调用流程，然后祈祷没有漏掉什么。

这个项目从普通类型检查停止的地方开始。

你的 Agent 工程其实早已有合同，只是它们散落在 Prompt、Schema、Tool、MCP Server、Skill、模型路由、权限、Pipeline，以及消费模型输出的业务代码里。

系统平时看起来可以运行——直到某个字段被改名、备用模型不支持结构化输出、一个工具意外获得写权限，或者生产环境执行的 Prompt 已经不是审核时的版本。

这个问题会越来越普遍，因为 Prompt 本身也经常由 AI 生成、扩写或重构。AI 让修改 Prompt 变得非常便宜，也让一次看起来很合理的大改更容易在没有充分审核的情况下被接受。一次“升级”可能保留了大致含义，却悄悄删除必要指令、修改字段概念、重复注入上下文、保留过期文字，或者破坏 Prompt、Schema 与消费代码之间的合同关系。

编译器会根据结构证据指出当前能够证明的漂移；至于新文字是否真的改善模型效果，必须通过 Evaluation 判断，不能伪装成编译期结论。

Agent Build Guard 把这些隐藏关系转换为带源码位置的 Agent IR，连接当前支持的系统部分，并在部署前报告已证明的失败和明确的分析缺口。

不接管你的 Agent，只让它变得可检查。

[!IMPORTANT] 0.1 已经是可运行的垂直切片原型，但还不是稳定 API。当前支持 Native 与框架无关的 Markdown Contract、YAML Sidecar、JSON Schema、部分 TypeScript/Zod 模式、确定性构建产物和本地只读图形 UI。没有专用 Adapter 时，明确不支持框架自身的工作流语义。

分析项目之前，请先了解这个边界

默认分析器不使用 LLM。 它确定性读取仓库里的静态材料，而不只是可执行代码，包括 TypeScript/JavaScript、Markdown Prompt、YAML Contract、JSON Schema、Sidecar 和依赖清单。它不会执行目标项目、安装目标依赖、写入目标仓库或访问网络。

静态证据可以证明当前支持的 Prompt → LLM Call → Schema → Output Field → Consumer 关系，但不能安全猜测运行时选择的 Builder、动态拼装值、Prompt 真实意图或模型质量。这些会被保留为明确的覆盖缺口，未来可以由 Contract、Runtime Trace 或可选 LLM 迁移助手补充。LLM 建议只有经过确定性编译器验证后才能被信任。

0.1 采用 Native-first，并保持框架无关。 如果检测到已知 Agent 框架，通用静态分析仍会继续，但不会分析框架专属的工作流、状态、路由和运行时语义。编译器会发出 AB1903，Manifest 会记录 semantics: "not-analyzed"。识别到框架不等于已经适配。

0.1 使用方式

从源码仓库运行时，统一使用项目脚本，不要求用户每次通过 npx 调用：

# 首次安装项目依赖
npm install

# 日常重复执行
./scripts/agent-build check
./scripts/agent-build build
./scripts/agent-build ui

npm 包发布后，全局安装会提供同一个 agent-build 命令：

npm install --global agent-build-guard
agent-build check --project /path/to/your-agent

面向人的 check 输出会在结尾给出打开同一项目交互 UI 的准确命令；build 还会输出生成报告的可点击 file:// 地址。JSON 输出保持为纯机器可读数据，供 CI 和脚本稳定解析。

脚本会在执行前检查必要环境。如果缺少受支持的 JavaScript Runtime 或本地依赖，会给出可以直接操作的错误提示。AST Parser、Schema、Graph 和 UI Library 都是一次安装的项目依赖，不要求用户逐个安装分析工具。

如果某个 Frontend 需要完整的 TypeScript 符号解析，被分析项目可能需要先安装自己的依赖。基础文件、Native Contract、Sidecar、Markdown、YAML 和 JSON Schema 检查不应该要求构建或运行目标应用。

默认检查不需要 LLM 凭证、模型服务商或网络连接。未来可以通过独立 Binary 或 Installer，进一步移除最终用户对 JavaScript 工具链的依赖。

“不需要 LLM”不等于“输入只有可执行代码”。确定性分析器读取仓库里的静态材料：TypeScript/JavaScript、Markdown Prompt、YAML Contract、JSON Schema、Sidecar 和依赖清单。它只证明这些材料能够支持的关系；动态分发和运行时拼装的 Prompt 会成为明确的覆盖缺口，而不会被猜测补齐。未来可选的迁移助手可以提出候选 Contract，但只有通过确定性编译验证后才能被信任。

为什么需要它

Agent 工程的很多故障发生在单独看来都合理的组件之间：

Prompt 要求一个字段       调用代码没有提供
Schema 要求一个属性       Prompt 从未要求模型生成
Tool 已经注册             组件的权限合同禁止该副作用
主模型运行正常            Fallback 不支持必要能力
流程图看起来完整          一个分支没有产生必要状态
源码已经通过审核          生产环境动态拼出了另一个版本

类型检查器只能看到代码，Schema validator 只能看到数据，Agent 框架主要理解自己的运行时，MCP 主要定义协议边界。它们不一定能够看到整个 Agent 应用的完整合同。

Agent Build Guard 补的是这一层全局连接能力。

0.1 已经实现其中 Prompt、Schema、调用位置、直接消费者和 Sidecar 的连接；上面列出的其他连接仍是明确的路线图能力。

它适合谁

典型使用情景

以下情况适合使用 Agent Build Guard：

• 修改了 Prompt、Schema 或结果字段，需要追踪静态分析器当前能够识别的调用位置和下游消费者；
• Prompt 分散在文件加载、Renderer、Wrapper 和 Builder 中，普通 Code Review 已经看不清完整路径；
• 老项目一直可以运行，但团队没人能确定每个 LLM 调用最终收到哪个 Prompt 和 Schema；
• Vibe Coding 原型开始成为正式产品，跨文件的隐含假设正在变成风险；
• AI 生成或升级了很长的 Prompt，需要确认输入、输出、约束和下游假设是否发生漂移；
• 希望在不运行、不修改目标项目的前提下，在本地或 CI 得到确定性检查和可视化依赖报告；
• 动态 Builder 或 Schema 无法静态解析，希望工具明确说明缺口，而不是让 AI 猜一个答案；
• 项目使用已知 Agent 框架，希望先获得框架无关的通用覆盖，同时清楚看到框架专属语义尚未支持。

现在适合尝试 0.1 的开发者

• Agent 应用开发者：使用 TypeScript/JavaScript，并使用 Markdown Prompt、Zod、JSON Schema 或 YAML Sidecar。
• 成熟 Agent 产品维护者：修改稳定 Prompt Pipeline 之前，需要在不改源码的情况下恢复结构。
• Vibe Coding 与独立开发者：希望尽早看清项目结构，避免隐含关系变成长期技术债。
• 平台与开发者体验工程师：正在评估可用于多个仓库的确定性本地或 CI 检查层。
• Reviewer 与技术负责人：需要带源码位置的依赖图和明确的能力边界，不想再靠人工还原系统。

Python AST 和框架专属 Adapter 不属于 0.1。当前可以通过 Python 依赖清单识别已知框架边界，但还不会编译 Python 源码语义。

成熟 Agent 项目

大型仓库中积累了大量稳定但隐含的行为。团队需要在不改写成熟 Prompt 的前提下恢复系统结构、分析变更影响、审核权限、验证构建与生产一致性，并通过 Sidecar 渐进接入。

新项目与 Vibe Coding 项目

快速生成的项目会在作者还没意识到需要声明合同时，就积累大量跨文件假设。它们需要接近零配置的建议模式：自动还原真实流程，用直白语言解释连接错误，并在偶然形成的结构变成长期技术债之前生成候选合同。

底层引擎相同，但使用体验不同：

成熟项目  -> 保留源码、恢复合同、控制变更
新项目    -> 尽早发现结构、解释风险、防止漂移

新手不应该先理解 Agent IR、也不应该先编写大量 Sidecar 才能获得价值。首先自动发现，再用显式合同逐步增强保证。

v0.1 能力列表

0.1 最适合 Prompt 与 Schema 关系能够从源码静态证明的 TypeScript/JavaScript Agent 项目。目前最完整的使用路径是 Markdown Prompt、Zod 或 JSON Schema 输出，以及按需添加的 YAML Sidecar。

v0.1 已支持

| 方面 | 当前能力 | | --- | --- | | 项目源码 | 在不执行目标项目的前提下，读取选定 TypeScript/JavaScript、Markdown、YAML、JSON Schema 和根目录依赖清单 | | Markdown Prompt | 解析普通 Prompt Markdown、模板变量和源码位置 | | Native Prompt Contract v0.1 | 按公开 Schema 验证稳定的 agent-build/[email protected] 输入/输出 Frontmatter；新项目和小项目可以在 agent.build.yaml 中强制要求，但工具不会写源码 | | Prompt 文件加载 | 解析 Markdown ?raw Import，以及使用字符串路径、process.cwd()、import.meta.url、new URL、静态 path.join/path.resolve 的 readFileSync 路径 | | 写在代码里的 Prompt | 把直接字符串、模块/局部常量、模板字符串、字符串拼接、字面量数组 .join() 和有界本地 Builder 连接到受支持的 LLM 调用 | | Prompt Renderer | 分析选定的 renderPrompt、renderPromptWithBudget 数据流，检查缺失和过期输入 | | LLM 调用与 Wrapper | 分析 callLLMForTask，以及能够证明 Prompt 参数和固定 Schema 的有界本地 Wrapper | | 模型 SDK 调用 | 识别有真实 Import 证据的部分 OpenAI、Azure OpenAI、Anthropic、Google GenAI、Vertex AI、Mistral、Cohere 和 Vercel AI SDK 操作，并向上追踪受支持的 Prompt 参数 | | Tool 发现 | 发现受支持的 Vercel AI SDK tool() / dynamicTool() 与内联 Tool 定义，并用 uses_tool 连接受支持模型调用 | | MCP 发现 | 发现有 Import 证据的部分 MCP Client/Server 注册、连接、发现和调用操作，但不声称远端服务可用 | | 输出 Schema | 解析 JSON Schema Object、直接/嵌套 Zod Object、Optional 字段、真实本地 Import，以及有界本地/跨文件 Schema Factory | | 下游消费者 | 把直接 result.field 读取连接到已证明的输出字段，并报告 Consumer/Schema 漂移 | | 现有老项目 | 通过通用 YAML Sidecar 绑定源码文件、Symbol、Fingerprint 和 Schema，不重写成熟 Prompt | | Agent IR 与诊断 | 输出带源码位置的节点、边、证据等级、稳定 Hash、Text/JSON 诊断和明确覆盖缺口 | | CLI 与 UI | 确定性执行 check/build，生成 JSON 与静态 HTML，并提供只绑定 localhost 的四语言只读 UI | | 安全边界 | 不执行目标代码、不安装目标依赖、不调用 LLM、不访问网络、不写入外部目标仓库 | | 框架边界识别 | 识别 LangGraph、CrewAI、OpenAI Agents SDK、Google ADK、AutoGen、Pydantic AI、Semantic Kernel、Mastra 和 LlamaIndex 依赖，并产生 AB1903 |

v0.1 部分支持

| 方面 | 准确边界 | | --- | --- | | TypeScript/JavaScript AST | 只支持选定语法和有界本地数据流，没有完整 TypeScript Type Checker 或全程序 Symbol Resolution | | 代码内 Prompt 值 | 能够证明静态源码形状和插值槽，但不知道最终插值后的运行时文本 | | Prompt Builder | 只支持返回值能够直接看出是字符串、模板、拼接、字面量数组 .join() 或受支持 Renderer Flow 的 Builder | | Schema Factory | 支持有界直接返回、Wrapper、Import 和部分基础 Schema Refinement；计算型 Key 与运行时选择成员仍无法解析 | | 已知 Agent 框架 | 仍会分析框架无关的受支持文件，但不解释框架自身的工作流、状态、路由和运行时语义 |

v0.1 不支持

• Python 源码 AST、Python Prompt 或 Schema 数据流；Python Manifest 仅用于识别框架边界。
• 任意模型厂商 SDK 调用形状；无法识别的 OpenAI、Anthropic、Gemini 或框架调用需要专用分析适配器，或者转换为受支持的本地 Wrapper 模式。
• 运行时选择的 Builder Registry、反射、插件分发、依赖数据的分支、动态 Import，以及从数据库、网络或配置服务加载的 Prompt。
• 完全动态生成的 Schema Key 或运行时选择的 Schema 成员。
• 框架专属图语义，包括 LangGraph 节点、State、Edge、Routing，以及其他框架中的对应概念。
• 证明 Prompt 文字写得好、相关、不重复、事实正确，或者某句话必然决定某个输出字段。
• 自动改写或删除成熟 Prompt 文字。

无法支持的关系会成为明确的覆盖缺口，而不是被猜测补齐：AB1901 表示 Prompt 无法解析，AB1902 表示动态 Schema，AB1903 表示检测到但未分析的框架语义。

未来路线图——不是 v0.1 承诺

| 规划能力 | v0.1 状态 | | --- | --- | | 跨环境 Tool 与 MCP 可用性 | 尚未实现；源码发现已实现，部署与可达性检查未实现 | | 权限与副作用可达性 | 尚未实现 | | Pipeline 分支与 Artifact 检查 | 尚未实现 | | 模型与 Fallback 兼容性 | 尚未实现 | | Context 与 Token 预算 | 尚未实现 | | Runtime Trace 一致性 | 尚未实现 | | Python AST 与框架 Adapter | 尚未实现 | | SARIF 与编辑器集成 | 尚未实现 | | 可选 LLM 迁移助手 | 尚未实现；未来建议仍然不具权威性 | | Prompt Span 语义溯源、冲突分析和基于 Evaluation 的消融 | 尚未实现 |

已实现诊断

以下检查已经由确定性编译器实现：

| 已实现检查 | 示例 | | --- | --- | | 未声明的 Prompt 变量 | 使用了 {{audience}}，但 Native 输入 Contract 没有声明它 | | 已声明但未使用的 Prompt 输入 | 声明了 staleValue，模板却从未引用 | | renderPrompt 缺少输入 | 调用位置没有提供 Prompt 必需的 audience | | 调用方仍传入过期输入 | 代码传入 legacyContext，Prompt 已经不再引用 | | 静态代码 Prompt 路径 | 把直接字符串、常量、模板字符串、字符串拼接、字面量数组 .join() 或有界本地 Builder 连接到 LLM 调用 | | 输出 Schema 无法解析 | Native 或 Sidecar 输出绑定找不到对应 Schema | | 输出与消费者漂移 | 代码读取 result.citations，但已证明的 Schema 没有该字段 | | Sidecar 源码漂移 | 绑定的文件、Symbol 或源码 Fingerprint 已经不匹配 | | 静态覆盖边界 | 动态 Prompt、动态 Schema 或已知框架语义无法被确定性证明 | | 必需 Native Contract 无效 | Prompt 缺少 agent-build/[email protected]、包含未知字段，或输入/输出类型声明无效 |

目标诊断形式类似：

error[AB1003]: prompt requires input `audience`, but this renderPrompt call does not supply it
  --> prompts/summarize.prompt.md:18:1

contract:
  summarizeDocument.inputs.audience: string

help:
  connect an upstream artifact or declare the input optional

每条诊断都应该说明源码位置、违反的合同、判断证据和修复路径。

它不是另一个 Agent 运行框架

Agent Build Guard 不负责编排 Agent，不代理模型调用，也不要求工程迁移到新框架。

现有 Agent 工程 ------------------------------> 原有运行时
      |
      +-- 只读 Frontend / Sidecar
                       |
                       v
                    Agent IR
                       |
          Linker -> 分析 Pass -> 构建产物

默认采用渐进式旁路接入：

1. Inspect：只读分析仓库，不修改源码。
2. Describe：只为无法可靠恢复的关系添加 Sidecar Contract。
3. Validate：在本地或 CI 中运行确定性检查。
4. Instrument（规划中）：可选地把构建身份写入 Runtime Trace。
5. Migrate：只有用户主动选择时，才迁移到原生合同或修改源码。

从 CI 中移除 Agent Build Guard 不应该改变应用的运行方式。运行时埋点必须是可选且显式的。

产品架构：已实现核心与规划扩展

长期目标的编译单元不是单独的 Prompt，而是相互连接的 Agent 系统：

Prompt + Skill + Schema + Tool + MCP + Model + Memory
       + Permission + Pipeline + Artifact + Consumer
                              |
                           Frontends
                              |
                           Agent IR
                              |
         Parse -> Link -> Type -> Effect -> Budget -> Policy
                              |
       诊断 / 依赖图 / Manifest / 影响报告 / Eval Plan
                         / Trace Contract

特定框架的解释逻辑属于 Frontend，公共检查逻辑作用于统一 Agent IR。

0.1 已经能够把受支持的 Prompt、Schema、LLM Call、Tool、MCP、输出字段、消费者、源码和框架检测边界转换为 Agent IR。模型能力、Memory、Permission、Pipeline、Effect、Budget、Policy、跨环境可用性和 Trace Pass 仍属于规划能力。

0.1 的 Native-first 框架边界

0.1 首先服务 Native 与框架无关的 Agent 项目。它会识别 LangGraph、CrewAI、OpenAI Agents SDK、Google ADK、AutoGen、Pydantic AI、Semantic Kernel、Mastra、LlamaIndex 等已知依赖，但“识别到”不等于“已经适配”。编译器会继续执行通用静态分析，同时发出 AB1903；Manifest 会把检测到的框架记录为 semantics: "not-analyzed"。

只有专用 Adapter 能够把某个框架的工作流语义可靠地下沉到 Agent IR 时，我们才声明支持该框架。Adapter 应该是明确的模块或包，而不是长期维护的产品分支，也不能把框架概念塞进公共编译器核心。

确定性核心与可选 AI 助手

项目包含两个相互分离的产品边界。

确定性编译系统

结构化解析器通过 AST、符号、Schema、配置、原生合同和 Sidecar 建立可复现的依赖图。已经实现的解析、连接、Schema 检查、诊断和构建身份会对相同输入产生相同结果；未来的权限与 Policy Pass 也必须保持这一确定性保证。

可信的 check 路径不依赖 LLM，也不依赖网络。

可选 AI 迁移助手

成熟项目往往包含动态 Prompt 拼装、隐式命名规则，以及单靠语法无法恢复的关系。可选助手只针对确定性分析留下的空白提出候选：

• 组件身份；
• Producer-Consumer 关系；
• Sidecar Contract；
• Prompt 片段到输出字段的连接；
• 语义冲突警告；
• Evaluation Requirement。

AI 输出永远不是权威结果。它只是候选，必要时由人确认，最后仍要交给确定性编译器重新验证。

AI 负责提出候选，编译器负责证明，人只处理剩余歧义。

一个标准 Skill，不做厂商分叉

0.1 提供一个符合开放 Agent Skills specification 的标准 Inspection Skill：

agent-build/
  SKILL.md
  scripts/
  references/
  assets/

不存在单独的 Codex Skill、Claude Skill 或其他厂商版本。任何兼容宿主都读取同一份 SKILL.md，并调用同一个编译器 CLI 或机器可读接口。

不同宿主的差异必须留在标准 Skill 之外：

• 编译器提供可移植的 CLI 和 JSON 合同；
• 可选宿主 Adapter 只转换 Tool 调用方式，不改变工作流语义；
• 正确性不能依赖尚未被各宿主统一支持的实验字段；
• Canonical Skill 中不复制厂商专用指令；
• Conformance Fixture 验证不同宿主最终得到相同的确定性编译结果。

当前 Skill 调用的是确定性检查工作流，并不是已经实现的 LLM 迁移助手。未来的可选助手必须扩展同一个可移植 Package，而不是产生按厂商拆分的副本。编译器才是事实来源。

不制造虚假的确定性

每一条重要关系都记录证据来源：

| 证据等级 | 含义 | | --- | --- | | proven | 由语法、合同、符号或 Schema 确定性推导 | | observed | 在某一次受控运行中真实观察到 | | inferred | 由启发式规则或 LLM 推测，仍需确认或评估 |

推断分数再高，也不能因为超过某个阈值就自动变成证明。

字段级 Prompt 溯源

组件级依赖图能够帮助理解系统，字段级溯源则能直接支持修改和排错：

输入 evidence
   -> Prompt 片段：“单独列出尚未解决的不确定性”
   -> Summary.uncertainties[]
   -> JSON Schema 约束
   -> 下游 warning panel
   -> uncertainty-recall evaluation

这个未来层的目标是回答：

• 哪段指令应该生成这个输出字段？
• 哪些输入为该字段提供数据？
• 哪段下游代码消费它？
• 修改这句话可能影响哪些字段和测试？
• 是否存在只有 Schema、没有 Prompt 支撑的字段？
• 是否存在提出了要求、却没有输出落点的指令？
• 哪些 Prompt 片段被重复注入、无法到达，或与任何输出和策略都没有关系？
• 哪些疑似无效片段应该先进行消融评估，再决定是否删除？
• 哪些声明必须通过运行评估，而不能静态证明？

0.1 已经能够表示 Schema 字段和直接消费代码，但还不能自动把普通 Prompt 句子映射到输出字段。未来的显式绑定可以被确定性证明；普通自然语言的影响关系必须保持为 inferred，除非获得更强证据。详见 Evidence and Field Lineage。

Roadmap：Prompt 浪费分析

0.1 当前能够检测未使用的模板输入，以及无法静态恢复的 Prompt 拼装路径。重复片段、不可达 Prompt Span、语义过期、指令冲突和 Prompt-to-field 相关性仍属于规划能力。未来的启发式规则或可选 AI 助手可以标记可疑指令，但必须将结果标记为 inferred。

“语义上没有价值”不是单靠静态分析就能证明的事实。在删除成熟 Prompt 之前，工具应该生成消融评估计划，对比移除可疑片段前后的质量、安全性、延迟和 Token 成本。删除必须由用户选择，并提供完整 Diff 和评估证据。

即使遵守最佳实践，为什么仍然会遇到这些问题

现代框架和协议已经解决了很多重要的局部问题：

• 图框架描述 Node、Edge 和共享 State；
• Typed Output 校验模型返回值；
• Tool 与 MCP Schema 校验单次工具调用；
• Guardrail 检查特定的运行时输入、输出或 Tool Call；
• Skill 封装可复用指令和资源；
• Tracing 记录执行后发生了什么。

这些能力都很必要，但它们处于不同边界。一个项目即使认真采用这些最佳实践，仍然可能在连接处出错：Prompt→Schema、Schema→Consumer、Skill→Host、Tool→Permission、Primary Model→Fallback、Source→Runtime，以及 Trace→Reviewed Build。

Agent Build Guard 不替代这些最佳实践，而是把它们连接起来。

当前生态也清楚体现了这些边界：LangGraph 的编译主要检查 LangGraph 应用内部的图结构；MCP 标准化单个 Tool 的 Schema，并明确把 Tool Annotation 视为不可信提示；Agent Skills 定义可移植的 Skill 包，但 allowed-tools 仍是实验字段；运行时 SDK 的 Guardrail 作用于特定输入、输出或 Tool Call；GitHub Agentic Workflows 则证明了在 GitHub Actions 这一特定领域进行编译期加固的价值。它们都是重要基础设施，但还不是连接所有边界的完整应用 Linker。

参考：LangGraph Graph API · MCP Tools · Agent Skills specification · OpenAI Agents SDK guardrails · GitHub Agentic Workflows compilation

两种接入模式

现有项目：Source-Preserving Overlay

保留成熟 Prompt 和 Agent 代码。Frontend 与 Sidecar Contract 把现有文件和符号绑定到 Agent IR，保留源码位置，并记录 fingerprint 以检测漂移。

新项目：Native-First Contract

新项目和小项目可以在 agent.build.yaml 中强制采用已经实现的 agent-build/[email protected]：

standards:
  promptContract: agent-build/[email protected]

每个 Prompt 只声明 v0.1 真正会验证的 contract、id、version、inputs 和 output。公开的 JSON Schema 定义同一边界。Prompt 正文仍然是普通 Markdown；Agent Build Guard 不初始化项目，也不会替用户写入 Contract。

项目明确不做什么

• 不声称能够证明 LLM 回答事实正确。
• 不声称能够静态证明 Prompt 写得好或任务效果更好。
• 不自动改写成熟 Prompt。
• 不把 LLM 生成的迁移结果当作权威事实。
• 不替代运行时沙箱、Guardrail、Eval 或人的判断。
• 不要求所有框架采用同一种运行时或通用 DSL。

能够证明的结构问题进入编译；不能证明的语义问题进入 Evaluation Requirement。

已实现的 0.1 范围

第一个垂直切片保持足够小：

1. 解析 Native Markdown Prompt Contract 和通用 YAML Sidecar；
2. 把 Native、Sidecar、JSON Schema、TypeScript 和直接 Zod 定义转换为同一个 Agent IR；
3. 连接 Markdown Raw Import、可静态求值的 readFileSync Loader、直接字符串、模块/局部 Prompt 常量、模板字符串、字符串拼接、字面量数组 .join()、有界本地 Prompt/LLM Wrapper、Budget Renderer、callLLMForTask、已识别的 OpenAI/Azure OpenAI/Anthropic/Google GenAI/Vertex AI/Mistral/Cohere Client 调用、Vercel AI SDK 函数调用、Tool 定义和使用、MCP 注册和调用、依据真实 Import 绑定的 Zod 输出、Schema Parser、可解析的 Schema Factory 和直接下游字段读取；
4. 输出带源码位置的确定性诊断、稳定 Contract Hash、JSON 构建产物和静态 HTML 报告；
5. 通过只绑定 localhost 的小清新卡片式只读分析工作台，先用数据驱动的文字摘要说明各方面结果，再展示依赖链、证据、搜索和诊断，并支持英语、简体中文、西班牙语和日语 Locale；
6. 拒绝把构建产物写入外部目标仓库；
7. 通过一个符合标准的 Agent Skill 暴露同一套 CLI。

TypeScript Frontend 只解析有语法证据的 Import 和有界本地数据流。SDK 锚点发现路径必须同时看到受支持 Client 或函数的真实 Import 和已知调用路径；仅仅方法也叫 .create() 或函数也叫 generateText() 不会被当成模型调用。它会从 input、instructions、system、message(s)、content(s)、parts 和 text 向上反向追踪静态 Prompt。精确发现按稳定源码身份和图关系去重，而不是按显示名称去重：同一个 AST 组件被多条路径命中时仍是一个节点，两个确实独立但同名的 Tool 则不会被错误合并。对于代码内 Prompt，它能够证明静态源码形状和插值槽，但不会声称知道插值后的最终运行时文本。运行时选择的 Builder 会产生 AB1901，动态 Schema 会产生 AB1902。计算型分发、完整 TypeScript Symbol Resolution、Python AST、框架 Adapter、通用 HTTP 模型调用、运行时埋点、字段级语义推断和 LLM 辅助迁移仍属于后续工作。准确边界见能力列表。

工作原则

Native-first，Adapter-friendly，Source-preserving。
核心保持确定性，每条关系都携带证据。
只有必须进行语义推断时才使用 LLM。