Neckbeard：面向 AI Agent 的 DevOps、平台工程与 SRE 插件

一款为你的编码 Agent 准备的插件：将应用转换成真正可供审查的云基础设施，并附上每月账单。

编码 Agent 很擅长应用代码，但对基础设施却有一种不合时宜的自信。让它“把这个部署到 AWS”，你大概会得到 300 行看似合理的 HCL、一个向全网开放的安全组、一份含有星号的 IAM 策略，以及对成本毫无概念的方案。读起来就像出自一个看过所有博客文章、却从未被半夜告警过的人之手。模型并没有骗你，它只是从未见过账单。

neckbeard 将这项工作拆分开来。人类维护一个 OpenTofu 模块目录：这些模块有版本控制、每次变更都会在 CI 中接受测试，并且每个模块只对应一种明确的工作负载形态：一个容器镜像、最多 10 个 HTTP、Worker 和 Cron 进程、Postgres、对象存储与密钥。Agent 读取你的代码仓库，判断应用需要什么，向你询问代码无法回答的问题，再将答案映射到目录输入中。其间的一切都由确定性的 Go 代码完成。规划器会写入经过哈希验证的 blueprint.yaml，渲染器是其纯函数，重新生成时会拒绝覆盖你手动修改过的文件。Agent 永远不会凭空发明基础设施。如果你的应用需要 Redis，你会得到一条明确的发现项，说明目录尚未支持 Redis，而不是一个“看起来也许能用”的模块。

它覆盖 AWS、GCP 和 Azure，支持 GitHub Actions 或 GitLab CI，并可部署为无服务器容器（Cloud Run、ECS Fargate、Container Apps）或 Kubernetes（EKS、GKE、AKS）。插件形态借鉴自 ponytail，后者证明了一个插件主要可以由一条优秀的提示词构成。

Claude Code 使用以下两条独立命令：

/plugin marketplace add bealesh/neckbeard

/plugin install neckbeard@neckbeard

然后打开你的应用仓库并运行 /neckbeard:analyze。你的第一条 neckbeard 命令会安装插件驱动的小型 CLI（经过 sha256 校验的发布二进制文件；如果本地有 Go，也可使用 go install），这就是全部配置。成本估算和验证依赖于你可能已经安装的工具，即 Infracost、OpenTofu 和 Checkov。/neckbeard:doctor 会告诉你缺少什么，以及每个工具能带来什么能力。

Codex、Cursor 或任何会读取 SKILL.md 的工具：请参阅 INSTALL.md。

运行 /neckbeard:analyze 后，Agent 会像一位细心的新员工那样阅读代码仓库：Dockerfile、暴露的端口、环境变量、健康检查端点、Procfile，以及 Django 在 settings.py 某个角落里悄悄读取 DATABASE_URL 的位置。它会写出一份应用档案：每项事实都附带文件和行号，每项推断都带有置信度，每个假设都被明确标出。随后，它会询问那些它确实无法得知的问题：预期流量有多大、你可容忍多长时间的宕机、这个 Postgres 是你已经在运行的还是希望新建的、Worker 的用途是什么。你的回答会记录在它们所消解的假设旁；只要仍有任何问题未解决，规划就会拒绝运行。

/neckbeard:estimate 会根据目录进行规划，并在任何资源创建之前展示账单。/neckbeard:sync 会搭建基础设施、流水线，以及在 Kubernetes 场景下生成集群清单；随后对它们进行验证，并精确说明它证明了什么、没有证明什么。之后，你可以像审查任何其他 Pull Request 一样审查这些文件，并针对每个环境执行一次生成的 docs/bootstrap.md，真实凭证始终由你自己掌握，Agent 永远拿不到它们。

没有人会在账单到来之前告诉你基础设施的成本，而这是一种奇怪的工程决策方式。因此 neckbeard 会先询问 Infracost。相同的参考应用（一个 HTTP 服务、一个 Worker、一个 Cron 任务和 Postgres）、最小规格、三个环境、实时价格：

| Cloud Run | Container Apps | ECS Fargate | EKS | GKE（区域） | AKS
---|---|---|---|---|---|---
月度成本 | $77 | ~$98* | $250 | $396 | $754 | ~$801*

星号很重要。Infracost 目前还无法为 Container Apps 计算计算资源成本；诚实的做法是直接说明这一点，而不是让一个偏低的数字误导你。因此，报告会将每个无法定价的资源与总价并列展示。其余部分则是任何真正读过自己名下云账单的人都会期望看到的内容：将空闲基线成本与使用量成本分开、将可编辑的使用量假设明确写出、提供低位、预期和高位情景，并在页脚说明数字来源。这张表也是工具表达建议的方式。当独立开发者要求 Kubernetes 时，数字会说“现在还不需要”，这样就不必由其他人来劝阻。

它会声明什么，以及不会声明什么

基础设施工具长期以来有一种传统：暗示自己已经证明了比实际更多的东西。一次通过的 tofu validate 从来不意味着某个方案真的能部署。neckbeard 分三层报告，并坚持向你展示第三层：

V0 PASSED tofu validate [prd] V0 PASSED checkov policy [prd] every skip carries a written reason V0 PASSED kubeconform (clusters/) V1 NOT EXERCISED authenticated plan requires cloud credentials V2 NOT EXERCISED deployment verification requires cloud credentials

V0 是语法和策略。生成配置中的每一项 Checkov 跳过规则都附有书面原因，因为没有原因的跳过，是对你安全态势的谎言。V1 是经过认证的规划，V2 是经过验证的部署；两者都需要凭证，在人类实际运行之前都会保持为 NOT EXERCISED。当真实运行发生故障时，失败案例会进入公开的发现项账本，并从那里反馈到模块目录。第一次真实部署就产生了 10 条发现项，其中 5 条在当天下午转化为模块修复。降级路径会说明原因：Azure 加 GitLab 的合并请求规划无法进行联邦认证，因此生成的流水线会明确写出这一点，而不会以一种让你耗费整个晚上排查的方式失败。

提供三个相互隔离的环境，各自拥有独立状态，并通过规格预设确定容量。预设会明确流量、可用性、恢复目标，以及实际上有多少人能够运营这套系统。每一个预设值均可见，并可在目录经过测试的边界内覆盖；超出边界的内容会被标记，而不会被轻率认可。无论使用哪一种 CI，流水线都来自同一个内部模型：测试、构建、扫描（Trivy 会阻止 HIGH 和 CRITICAL）、推送；以只读身份在 Pull Request 上执行规划；以写入身份在 main 分支上执行应用；生产环境则受环境保护机制约束。系统中不存在任何静态云密钥。端到端使用 OIDC 联邦认证；如果渲染出的流水线哪怕只是提到了 AWS_SECRET_ACCESS_KEY，测试都会使构建失败。网络默认私有；密钥管理器仅保存由运营者填写的名称（密钥值永远不会经过 neckbeard、其状态文件或你的 Git 历史）；当规格层级需要时，托管 WAF 规则会自动启用。

处于 Pre-alpha 阶段，并且明确说明各部分状态。

该插件目前的产品能力是前半段：可审查的基础设施、流水线、成本估算，以及可交给凭证持有者的运行手册。底层的部署生命周期（技能文档中记录的 neckbeard release）已经存在，并且已在两条路径上真正运行成功；但在通过发布计划中的门槛之前，它仍属于实验性功能。静态验证并不是部署证明。Landing Zone，即组织结构与防护栏，在 DESIGN.md 中描述的 Path F 方案已经完成设计，但尚未构建。

        you / your agent                      deterministic core
    ┌──────────────────────┐            ┌───────────────────────────┐

repo ──▶│ analyze: facts w/ │ profile │ plan: catalog @ pinned │ │ evidence, questions, ├───────────▶│ versions → blueprint.yaml │ │ judgment, answers │ config │ (hash-verified lockfile) │ └──────────────────────┘ └─────────┬─────────────────┘ ┌──────────────┼──────────────┐ ▼ ▼ ▼ estimate scaffold validate Infracost, ownership V0 static, scenarios, contract: V1 plan, unpriced never silently V2 deploy, named overwrite each reported

仓库根目录就是该插件。skills/neckbeard/SKILL.md 是 Agent 的操作手册，commands/ 存放斜杠命令，而 cmd/ 下的 Go CLI 与 catalog/ 下的模块目录构成确定性的一半。CLI 完全不依赖 Agent 也能正常运行：

go install github.com/bealesh/neckbeard/cmd/neckbeard@latest neckbeard analyze && $EDITOR app-profile.yaml neckbeard.yaml neckbeard plan && neckbeard estimate && neckbeard scaffold && neckbeard validate

如果你在生产环境运行过足够久的系统，就会知道最昂贵的错误很少存在于应用代码中。它们存在于账户账单和凌晨 3 点的告警里。这是一款在这些问题还只是一次 diff 时就捕捉它们的工具。

如果你希望了解更多：DESIGN.md 是完整设计文档，从第一天起就持续保持诚实。docs/findings/ 记录了现实教会我们的事。CONTRIBUTING.md 说明如何参与贡献。

Apache-2.0，详见 LICENSE。

A plugin for your coding agent that turns an app into cloud infrastructure you can actually review, with the monthly bill attached.

Coding agents are great at application code and weirdly confident about infrastructure. Ask one to "deploy this to AWS" and you'll get three hundred lines of plausible HCL, a security group open to the world, an IAM policy with a star in it, and no idea what any of it costs. It reads like the work of someone who has absorbed every blog post and never once been paged. The model isn't lying to you. It has simply never seen the invoice.

neckbeard splits the job. Humans maintain a catalog of OpenTofu modules that are versioned, tested in CI on every change, and scoped to one honest workload shape: a container image, up to ten HTTP, worker, and cron processes, Postgres, object storage, secrets. The agent reads your repo, works out what the app needs, asks you the questions code can't answer, and maps the answers onto catalog inputs. Everything in between is deterministic Go. The planner writes a hash-verified blueprint.yaml, the renderer is a pure function of it, and regeneration refuses to overwrite a file you've touched. The agent never invents infrastructure. If your app needs Redis, you get a named finding that says the catalog doesn't do Redis yet, rather than a module that looks like it might.

It covers AWS, GCP, and Azure, with GitHub Actions or GitLab CI, as serverless containers (Cloud Run, ECS Fargate, Container Apps) or Kubernetes (EKS, GKE, AKS). The plugin shape is borrowed from ponytail, which proved a plugin can be mostly one good prompt.

Claude Code, as two separate prompts:

/plugin marketplace add bealesh/neckbeard



/plugin install neckbeard@neckbeard

Then open your app's repo and run /neckbeard:analyze. Your first neckbeard command installs the small CLI the plugin drives (a sha256-verified release binary, or go install if you have Go around), and that's the whole setup. Cost estimates and validation lean on tools you may already have, namely Infracost, OpenTofu, and Checkov. /neckbeard:doctor tells you what's missing and what each one buys you.

Codex, Cursor, or anything else that reads a SKILL.md: see INSTALL.md.

You run /neckbeard:analyze and the agent reads the repo the way a careful new hire would. Dockerfiles, exposed ports, environment variables, health endpoints, the Procfile, the corner of settings.py where Django quietly reads DATABASE_URL. It writes an app profile in which every fact carries a file and line number, every inference carries a confidence, and every assumption is loud. Then it asks you the things it genuinely can't know: how much traffic to expect, how much downtime you'll tolerate, whether that Postgres is one you already run or one you want built, what the worker is for. Your answers get recorded next to the assumptions they resolve, and planning refuses to run while any of them is still open.

/neckbeard:estimate plans against the catalog and shows you the bill before anything exists. /neckbeard:sync scaffolds the infrastructure, the pipelines, and on Kubernetes the cluster manifests, then validates them and tells you precisely what it did and didn't prove. From there you review the files like any other pull request and follow the generated docs/bootstrap.md once per environment, with real credentials in your own hands. The agent never gets those.

Nobody tells you what infrastructure costs until the invoice arrives, which is a strange way to make an engineering decision. So neckbeard asks Infracost first. Same reference app (an HTTP service, a worker, a cron job, Postgres), smallest tier, all three environments, live prices:

| Cloud Run | Container Apps | ECS Fargate | EKS | GKE (regional) | AKS
---|---|---|---|---|---|---
monthly | $77 | ~$98* | $250 | $396 | $754 | ~$801*

The asterisk matters. Infracost can't price Container Apps compute yet, and the honest move is to say so rather than let a low number lie, so the report lists every resource it couldn't price right next to the total. The rest is what you'd want from anyone who has read a cloud bill with their name on it: the idle baseline separated from usage, the usage assumptions written down where you can edit them, low, expected, and high scenarios, and a footer saying where the numbers came from. The table is also how the tool argues. When a solo developer asks for Kubernetes, the numbers say "not yet" so nobody else has to.

What it will and won't claim

Infrastructure tooling has a long tradition of implying more than it has proven. A passing tofu validate has never once meant a thing deploys. neckbeard reports in three levels and insists on showing you the third:

V0   PASSED         tofu validate [prd]
V0   PASSED         checkov policy [prd]        every skip carries a written reason
V0   PASSED         kubeconform (clusters/)
V1   NOT EXERCISED  authenticated plan          requires cloud credentials
V2   NOT EXERCISED  deployment verification     requires cloud credentials

V0 is syntax and policy. Every Checkov skip in the generated config carries a written reason, because a skip without one is a lie about your security posture. V1 is an authenticated plan and V2 is a verified deployment; both need credentials, and both stay NOT EXERCISED until a human runs them. When live runs break, the failures go into the public findings ledger and from there into the catalog. The first real deployment produced ten of them, and five became module fixes the same afternoon. Degraded paths say why: an Azure plus GitLab merge-request plan can't federate, so the generated pipeline says that out loud instead of failing in a way you'd lose an evening to.

Three isolated environments with their own state, sized by tier presets that spell out traffic, availability, recovery objectives, and how many people are actually around to operate the thing. Every preset value is visible and overridable within the catalog's tested envelope, and anything outside that envelope is marked rather than blessed. Pipelines come from one internal model for either CI: test, build, scan (Trivy blocks HIGH and CRITICAL), push, plans on pull requests under a read-only identity, applies on main under a write identity, production gated behind environment protection. There are no static cloud keys anywhere. It's OIDC federation end to end, and a test fails the build if a rendered pipeline so much as mentions AWS_SECRET_ACCESS_KEY. Networks are private by default, secret managers hold the names the operator fills in (values never pass through neckbeard, its state, or your git history), and managed WAF rules switch on where the tier calls for them.

Pre-alpha, and specific about which parts.

The plugin's product today is the front half: reviewable infrastructure, pipelines, a cost estimate, and a runbook you can hand to whoever holds the credentials. The deployment lifecycle underneath it (neckbeard release, documented in the skill) exists and has worked for real on two lanes, but it stays experimental until it clears the gates in the launch plan. Static validation is not deployment proof. Landing zones, meaning org structure and guardrails, the Path F story in DESIGN.md, are designed and not built.

            you / your agent                      deterministic core
        ┌──────────────────────┐            ┌───────────────────────────┐
repo ──▶│ analyze: facts w/    │  profile   │ plan: catalog @ pinned    │
        │ evidence, questions, ├───────────▶│ versions → blueprint.yaml │
        │ judgment, answers    │  config    │ (hash-verified lockfile)  │
        └──────────────────────┘            └─────────┬─────────────────┘
                                       ┌──────────────┼──────────────┐
                                       ▼              ▼              ▼
                                   estimate       scaffold        validate
                                   Infracost,     ownership       V0 static,
                                   scenarios,     contract:       V1 plan,
                                   unpriced       never silently  V2 deploy,
                                   named          overwrite       each reported

The repository root is the plugin. skills/neckbeard/SKILL.md is the agent's operating manual, commands/ holds the slash commands, and the Go CLI under cmd/ plus the module catalog under catalog/ is the deterministic half. The CLI runs fine without an agent at all:

go install github.com/bealesh/neckbeard/cmd/neckbeard@latest
neckbeard analyze && $EDITOR app-profile.yaml neckbeard.yaml
neckbeard plan && neckbeard estimate && neckbeard scaffold && neckbeard validate

If you've run anything in production for long enough, you know the expensive mistakes rarely live in the application code. They live in the account bill and the 3am page. This is a tool for catching them while they're still a diff.

More, if you want it: DESIGN.md is the full design, kept honest since day one. docs/findings/ is what reality taught us. CONTRIBUTING.md is how to help.

Apache-2.0, see LICENSE.