尧图网页设计 
Langflow AGENTS-example.md 解析一份面向 AI 编码代理的开发规范模板从权衡优先级到交付前检查清单【免费下载链接】langflowLangflow is a powerful tool for building and deploying AI-powered agents and workflows.项目地址: https://gitcode.com/GitHub_Trending/la/langflowAGENTS-example.md是 Langflow 仓库根目录提供的一份语言无关、框架无关的开发标准示例模板定义了从核心理念、设计原则、代码质量、架构分层到测试、评审与交付前检查的完整工程规范。本文以该模板为骨架逐节拆解其规则体系并结合 Langflow 仓库中的实际配置ruff、pytest、pre-commit、codecov与配套的docs/agents/文档、后端代码评审 Skill展示这份模板在真实项目中如何被适配、落地与强制执行帮助读者掌握为 AI 编码代理编写可执行开发规范的方法。模板的定位为什么 Langflow 需要一个 AGENTS-example.mdLangflow 仓库中存在多份面向 AI 编码代理coding agent的指引文件分工明确AGENTS.md项目级代理指引描述项目概览、前置条件Python 3.10–3.14、uv、Node.js与常用命令make init、make unit_tests、make alembic-revision等CLAUDE.md说明本项目采用 AGENTS.md 作为向 AI 代理提供上下文的标准通过AGENTS.md导入指令让 Claude Code 自动加载AGENTS-example.md本文主角——一个标注为 EXAMPLE 的参考模板作者明确提示使用需谨慎Use at your risk建议在采纳前先按项目需要适配docs/agents/PHILOSOPHY.md、docs/agents/ARCHITECTURE.md、docs/agents/TESTING.md 等Langflow 团队将模板思想适配到本项目后的实际产出如十项项目哲学、单向依赖边界、组件测试基类.agents/skills/backend-code-review/SKILL.md一个直接消费该模板规则的评审 Skill其中明确引用了 per AGENTS-example.md 的文件行数限制并把模板中的测试反模式Liar、Mirror、Giant、Mockery……逐条写进了评审规则。可以看出Langflow 的用法是模板提供通用规则骨架项目文档注入领域细节工具链Skill/pre-commit负责强制检查。这种模板 适配 执行的三层结构是本文解读该模板的主线。核心理念权衡优先级与基本规则第 1 节模板开宗明义地给出了冲突发生时的权衡优先级Trade-off Priority正确性Correctness—— 代码做它该做的事简洁与可读性Simplicity and readability—— 代码易于理解可测试性Testability—— 代码易于测试性能Performance—— 代码足够快抽象与复用Abstraction and reuse—— DRY。这个排序的潜台词是性能排第 4、抽象排第 5意味着先写对再写快最后才谈优雅。模板结尾也再次强调当拿不准时选择简单当权衡发生时遵循第 1 节的优先级。先构建正确性之后再做优化永远保持可测试。与之配套的基本规则Ground Rules共有五条修改前先阅读并理解现有代码遵循项目既有的模式与约定需求含糊时先提问再写代码优先增量交付先核心逻辑再边界情况最后打磨不过度工程化为今天的需求而建不为假想的未来而建。Langflow 自身的项目哲学文档 docs/agents/PHILOSOPHY.md 正是这种先问该不该做再问怎么做思路的产物其中第 11 条信条要求没有证据证明改动有效就不算修复先复现失败、再证明修复消除了它与模板中需求含糊时先提问一脉相承。设计原则SOLID、DRY、KISS、YAGNI第 2 节SOLID附常见误区的实现版解释模板没有停留在 SOLID 的口号上而是为每条原则配了规则 常见错误两列的表格原则规则常见误区SRP单一职责每个类/函数/文件只有一个变化理由。需要用到和/或来描述它时就该拆分把 SRP 误解为一个类一个函数。SRP 指的是一个变化轴OCP开闭原则通过写新代码而非改旧代码来增加行为在预期变化的地方用多态或策略模式过早抽象导致的过度工程。OCP 只适用于有证据表明需求会变化的地方LSP里氏替换子类必须遵守父类契约is-a 关系不严格时优先组合而非继承重写父类方法却直接抛NotImplementedError或什么都不做ISP接口隔离定义小而面向角色的接口客户端只依赖它用到的方法创建一个含 15 方法的上帝 service接口DIP依赖倒置在模块边界依赖抽象而非具体实现领域逻辑永远不 import 基础设施把 DIP 等同于用依赖注入就行。DIP 是反转源码依赖的方向值得注意的是 Langflow 的架构文档 docs/agents/ARCHITECTURE.md 将 DIP 落成了可检查的硬规则依赖图只能单向流动langflow → langflow-base → lfxlfx禁止 importlangflow.*并给出反例——在src/lfx/中from langflow.services.deps import session_scope 是违规写法正确做法是在lfx内定义接口、由应用层注入实现。这正是模板中依赖倒置从概念到边界的典型适配。DRY三条红线只有当完全相同的业务规则在 3 处以上重复时Rule of Three才抽取共享逻辑配置、常量、schema 定义保持单一事实来源宁可重复也不要错误的抽象。两段看起来相似但服务于不同业务目的的代码不是重复——强行合并会制造意外的耦合。错误的抽象被明确定义为过早泛化、目的不清、把无关关注点耦合在一起。KISS 与 YAGNI反过度工程的量化口径选择满足当前需求的最简实现标准库优先于自造轮子一次普通的函数调用胜过元编程只需要数据分组时字典胜过类不要以防万一地引入设计模式、抽象或框架只有存在具体的当前需求时才实现功能至少有两个具体用例之前不要搭通用/可扩展框架定期删除投机性代码和无用的 feature flag三行相似代码优于一个过早的抽象。代码质量命名、类型、不可变性与函数设计第 3 节命名规则名字应揭示意图回答它为什么存在、它做什么函数用动词get、create、update、delete、validate、format、parse布尔量用前缀is、has、can、should除非业界通用id、url、api否则不用缩写禁用泛化命名data、result、obj、thing、temp、misc、utils名字中不出现 and、or、then——出现即暗示承担了多个职责。这套命名规则在 Langflow 的评审 Skill .agents/skills/backend-code-review/SKILL.md 中被逐条复刻为检查项Functions should use verbs (get,create,validate). Booleans should use prefixes (is_,has_,can_,should_)说明它已超出示例范畴成为实际评审依据。强类型、不可变性与早返回强类型处处使用强类型避免any/object/dynamic/Object公共函数必须有带类型的参数与返回值不许为了编译通过而强转any。不可变默认不可变const、readonly、final、frozen、tuple、frozenset转换函数返回新对象而非原地修改绝不向外暴露可变内部集合只返回副本或只读视图函数内部的可变局部变量没问题——危险的是可变共享状态。早返回与守卫子句在函数顶部校验前置条件并尽早 return/throw通过取反条件、提前返回来降低嵌套让快乐路径停留在最低缩进层级。无魔法值重复出现的数字和字符串抽成命名常量用描述性变量名替代内联字面量。注释不注释显而易见的代码注释只解释WHY绝不解释WHAT不留注释掉的代码那是版本控制的工作TODO 注释必须带 ticket 引用。函数保持短小、单一抽象层级一个函数做一件事做两件事就拆分不用切换行为的布尔参数而是拆成两个具名函数每次改动都清除死代码和未使用的 import。从仓库的 lint 配置看这些规则有工具兜底pyproject.toml 中 ruff 配置select [ALL]、line-length 120、pydocstyle.convention google即几乎启用全部 lint 规则族并用 Google 风格 docstring 约定约束注释。架构分层职责、依赖注入与 DDD 的适用边界第 4 节关注点分离领域、应用、基础设施三层关注点必须分离领域/业务逻辑对框架、数据库、HTTP 层的 import 数量必须为零副作用I/O、日志、指标留在系统边缘业务逻辑保持纯粹层与层边界上使用 DTO 或值对象——永远不要把 ORM 模型或 HTTP 请求对象传进业务逻辑。分层职责表模板用一张 CAN / CANNOT 表格把五类层的边界钉死层可以不可以Handler/Controller接收输入、委派给 service、返回输出包含业务逻辑、直接调数据库Service/Orchestrator协调操作、执行业务规则感知 HTTP/传输细节、直接执行 SQLRepository/Data Access执行查询、映射数据做业务决策、调用外部 APIHelper转换数据、校验、格式化产生副作用、做 I/O、维护状态External Client与外部服务通信包含业务逻辑、访问数据库Langflow 的 docs/agents/ARCHITECTURE.md 给出了这张表的项目化版本——Service vs Utility vs Component三分类Service继承services/base.Service、经services/factory.py注册、有生命周期与共享连接的单例、Utility无共享状态、无生命周期的纯/近纯函数放helpers/或lfx/utils/、Component画布上用户可见的节点子类。它甚至点破了模板隐含的陷阱MyHelperService这种其实只是一堆函数的 service 是坏味道——工具函数就该是函数不该套 service 壳。依赖注入的五条细则通过构造函数或方法参数注入依赖让所有依赖显式化注入的是 I/O 边界数据库、HTTP 客户端、文件系统、时钟使它们在测试中可替换组合根composition root留在应用入口与业务逻辑分离一个类需要注入超过 ~4 个依赖时说明它职责过载应拆分只注入有副作用或随环境变化的东西纯工具函数不需要注入。DDD仅在值得时应用模板对领域驱动设计持谨慎态度仅当领域复杂度确凿地证明有必要时才引入 DDDEntity、Value Object、Aggregate 只在真正创造价值时使用错误与不变量也应建模为领域的一部分。这与 Langflow 哲学第 2 条每个后端能力必须落到画布上如果不能被非 Python 用户以组件形式接线它属于 SDK 而非平台的克制气质一致——先问值不值再谈怎么建。文件结构行数上限、职责分文件与命名禁区第 5 节单文件生产代码上限指标指南代码行数不含 import、类型定义、文档~500 行到 ~530 可接受600 是红旗承担不同职责的函数最多5 个承担相同职责同前缀的函数最多10 个文件内主类1 个小型相关类异常、DTO、枚举5 个且同类型Langflow 评审 Skill 对这一节做了显式背书生产文件超过 ~500 行……600 行应视为红旗……测试文件超过 ~1000 行应按逻辑分组拆分per AGENTS-example.md并解释了 500 行阈值背后的理由行数越大的文件缺陷率越高、评审越慢且是多重职责SRP 违规的信号。单职责文件与一句话测试每个文件必须有一个存在理由和一个变化理由。判据是一个测试能否不用和/或用一句话描述这个文件的用途按职责前缀分文件函数必须按职责类别分组不同前缀的函数不允许共存于同一文件职责函数前缀对应文件Types/Models类型定义、接口、无逻辑的类{feature}_typesConstantsMAX_*、DEFAULT_*、枚举{feature}_constantsValidationvalidate*、check*、is_valid*validationFormattingformat*、build*、serialize*、to_*formattingParsingparse*、extract*、from_*parsingExternal callsfetch*、send*、call*、request*{service}_clientData accesssave*、load*、find*、delete*、query*{feature}_repositoryOrchestration主入口、协调{feature}_serviceHandlers端点、控制器、视图{feature}_handler反过度拆分与命名禁区不要把 1–2 个合计不到 20 行的琐碎函数拆成独立文件私有辅助函数_func留在使用它的文件里一行工具函数不单独成文件拆分时机 出现清晰、可复用的职责合并时机 拆分只增加复杂度而无收益永远不用泛化文件名的独立文件utils、helpers、misc、common、shared。评审 Skill 给出的解释是叫utils.py的文件会在几个月内变成 50 个函数的垃圾场——每个函数组应放进以职责命名的文件formatting.py、validation.py。模板最后给出一张标准模块结构图feature/ ├── {feature}_service # Orchestration ├── {feature}_types # Type definitions ├── {feature}_constants # Constants and enums ├── helpers/ │ ├── validation # ONLY validation functions │ ├── formatting # ONLY formatting functions │ └── parsing # ONLY parsing functions ├── services/ │ └── {external}_client # ONLY external API communication ├── repositories/ │ └── {feature}_repository # ONLY data persistence └── handlers/ └── {feature}_handler # ONLY request handling错误处理错误是 API 契约的一部分第 6 节模板给出七条错误处理铁律显式处理预期错误零静默失败不用泛型异常Exception、Error、object使用领域相关错误类型抛出/返回的错误必须带上下文什么失败、什么输入导致的、如何修复;错误是 API 契约的一部分在系统边界校验输入非法数据快速失败区分可恢复错误与致命异常绝不静默地修正非法输入——用清晰消息拒绝它。配套的正反例代码# BAD try: result do_something() except: pass # GOOD try: result do_something() except ValidationError as e: logger.warning(Validation failed, extra{error: str(e), field: e.field}) raise DomainError(fInvalid input: {e.field}) from e要点在于 GOOD 写法做了三件事捕获具体异常类型、把失败记入结构化日志带field上下文、以raise ... from e保留异常链——而不是吞掉异常假装一切正常。安全默认拒绝与边界校验第 7 节模板的安全清单可以归纳为四组输入与信任边界在边界处净化并校验所有用户/外部输入永远不信任系统边界之外的数据使用白名单allowlist而非黑名单——默认拒绝只接受已知安全的模式复杂结构用 schema 校验库Pydantic、zod、JSON Schema不手写校验服务端校验永远不可省略——客户端校验只是 UX 便利不是安全措施。密钥管理密钥不进代码使用环境变量或 secret manager不允许硬编码 API key、token、密码。数据访问与错误输出SQL 一律参数化查询禁止字符串拼接面向最终用户的错误消息不暴露内部细节。测试数据测试中使用伪造/匿名数据绝不使用真实用户数据。在 Langflow 仓库中密钥不进代码这条规则由工具链闭环执行.pre-commit-config.yaml 配置了detect-secrets钩子以.secrets.baseline为基线扫描评审 Skill 也把硬编码密钥列为 Critical 级发现项。可观测性结构化日志、级别与 PII 零容忍第 8 节日志原则使用结构化日志key-value / JSON而非格式化字符串在关键决策点与边界处打日志而不是在紧循环内部日志应包含操作名、相关 ID、结果成功/失败、必要时耗时全代码库保持字段名一致。日志级别级别使用场景ERROR有东西坏了需要人工介入WARN降级但可自恢复INFO重要的业务事件DEBUG诊断细节生产环境关闭PII 零容忍绝不记录邮箱、用户名、手机号、住址、token、密码允许的标识符auth_id、user_id、internal_idprint()/console.log()不得携带用户数据——它们会流向生产日志。Langflow 的评审 Skill 把这一节细化到了具体实现层面统一使用lfx.log.logger的异步日志方法adebug、ainfo、awarning、aerror、aexception禁用print()与标准库logging允许的 ID 进一步收敛为user_id、flow_id、session_id异常输出统一用{e!s}表示法。测试测试代码就是生产代码第 9 节模板在此节的立场很强硬Test code is production code.它接受同样的打磨、评审与质量标准。核心原则为所有核心逻辑写单元测试遵循 AAAArrange-Act-Assert结构一个测试一个 act、一个逻辑断言测试必须相互独立、确定性、不依赖执行顺序Mock 或 fake 掉所有外部依赖DB、API、文件系统、时间、随机性测试命名清晰should_[expected]_when_[condition]。不仅要验证还要进攻这是本模板最有辨识度的部分。模板明确指出快乐路径测试只是地基单独的快乐路径测试是不够的。必须写主动进攻代码、寻找缺陷的对抗性测试意外的输入类型None、、[]、{}、0、-1边界值最大 int、最大长度、恰好等于上限、超过上限一格畸形数据缺字段、多字段、错误类型、非法格式错误状态依赖失败时会发生什么验证不该发生的事被禁止的状态被正确拒绝错误消息与类型不只验证它失败了还要验证它如何失败。并给出两条纪律基于需求/规格写测试而不是照抄源码当前的行为——这是捕捉代码偏离预期型 bug 的唯一手段测试失败时先问代码是不是错了而不是默默改断言去迁就现状——不理解原因就改断言是被禁止的。测试文件规则指标指南每文件行数~1000 行指南——超过可考虑拆分但覆盖单一模块时非强制每文件测试数无硬性上限——只在覆盖无关行为时才拆分SetupArrange每测试~20 行上限超出则抽取为 helper/factory原则是按逻辑边界拆分测试文件而不是按任意行数一个文件对应一个模块/服务即使 800 行也完全没问题。覆盖率80% 目标75% 底线目标 80%最低可接受 75%低于 75% 视为任务未完成重点盯分支覆盖if/else两侧、所有catch块而非仅仅是行覆盖没有断言的高覆盖率毫无价值——每个测试至少有一个有意义的断言覆盖率必须实际运行并展示后端和前端都要。模板给出的三类运行命令# Python pytest tests/your_tests.py --covsrc/module_under_test --cov-reportterm-missing --cov-branch -v # JavaScript/TypeScript (Jest) npx jest tests/your_tests.test.ts --coverage --collectCoverageFromsrc/module/**/*.{ts,tsx} # JavaScript/TypeScript (Vitest) npx vitest run tests/your_tests.test.ts --coverage所有创建的测试必须通过零失败、零异常禁止禁用/跳过/删除测试来掩盖失败禁止留下以后再修的测试覆盖率不足 75% 就继续补测试、重跑直到达标。不该测什么简单 getter/setter/trivial mapper 不值得测实现细节方法调用顺序、内部状态应该测行为来替代不要用无意义断言堆覆盖率。七大测试反模式禁止反模式问题The Liar骗子测试通过但没有验证它声称要验证的行为The Mirror镜子测试读源码然后断言代码恰好做了什么——零 bug 产出The Giant巨无霸50 行 setup、多个 act、几十个断言——应拆成 5 个独立测试The Mockery陪练mock 多到测试实际只测了 mock 的搭建过程The Inspector窥探者与实现细节耦合任何重构都把它打碎The Chain Gang连环犯测试依赖执行顺序或共享可变状态The Flaky飘忽者不改代码时有时过有时挂结合仓库实际可以看到这套规范的适配版取舍docs/agents/TESTING.md 针对模板中mock 掉所有外部依赖一条做了项目级修正——Langflow 明确避免 mock、优先打真实依赖因为mock 通过、生产失败曾让团队付出多个发布周期的代价mock 只保留给 LLMMockLanguageModel与真正不稳定且与被测逻辑正交的依赖需要凭据的测试打pytest.mark.api_key_required交给 CI 门控。而 codecov.yml 揭示了另一个现实仓库当前的整体覆盖率目标backend 55%、lfx 60%、frontend 10%、patch 40%是渐进式改进的定位与模板新代码 80%/75%的绝对要求并存——前者管存量大盘后者管每次新增的交付质量。模板命令在 Langflow 中的对应物是 AGENTS.md 中的make unit_tests并行、make unit_tests asyncfalse串行、uv run pytest path/to/test.pypytest 的 markerapi_key_required、security、real_services等统一声明在 pyproject.toml 的[tool.pytest.ini_options]中。代码评审Blocker 优先的评审顺序第 10 节模板定义了评审的固定优先级先处理阻断项安全与 PII—— 日志无 PII、无硬编码密钥、输入有校验DRY—— 无重复的类型、类、函数或逻辑文件结构—— 行数上限被遵守、职责已分离架构—— 单一职责、分层正确代码质量—— SOLID、强类型、错误处理测试—— 快乐路径与对抗性测试兼备、覆盖率达标可观测性—— 结构化日志、无 PII。针对测试的四个灵魂拷问是否同时有快乐路径测试与对抗性测试如果有人改坏了逻辑这些测试能否抓住回归是否存在没被覆盖的边界情况或失败模式如果我删掉一行业务逻辑是否至少有一个测试会失败对遗留代码的态度是不传染不延续坏模式即使周围代码很烂新代码也要写好的不未经评审就从遗留代码复制粘贴在可能的范围内把新代码与遗留隔离。Langflow 的 docs/agents/ARCHITECTURE.md 对这一点有精确表述langflow/base/是遗留目录不要再往里面加东西——新共享原语一律进src/lfx/src/lfx/base/。文档C4 分级与功能文档必备章节第 11 节何时写文档功能实现完成之后再生成功能文档文档与代码同仓存放Markdown使用通用语言ubiquitous language——文档、代码、沟通中使用同一套术语。C4 文档分级级别读者内容Context (L1)产品/干系人系统在其环境中的位置Container (L2)两者应用、数据库、队列Component (L3)工程团队内部服务细节功能文档的八个必备章节Overview—— 摘要、业务背景、限界上下文通用语言术语表—— 领域术语并附代码引用领域模型—— 聚合、实体、值对象、事件行为规格—— Gherkin 场景快乐路径、边界、错误架构决策记录ADR—— 上下文、决策、后果技术规格—— 依赖、API 契约、错误码可观测性—— 指标、日志、仪表盘部署与回滚—— feature flag、迁移、回滚预案。交付前检查清单代码出门前的最后一道闸第 12 节模板要求交付任何代码前逐项验证全部清单项。Critical阻断项任何日志、打印、webhook 消息中无 PII代码中无密钥或凭据无重复的类型、类或逻辑DRY无生产文件超过 ~500 行 / 测试文件超过 ~1000 行同一文件内无混合职责前缀的函数所有用户输入在系统边界被校验Important必须修复每个文件/函数单一职责恰当的错误处理无静默失败、错误信息有意义强类型无any、object、dynamic类型放专属 types 文件、常量放专属 constants 文件领域逻辑独立于框架/基础设施Testing强制所有核心逻辑有单元测试快乐路径与对抗性测试同时存在所有创建/修改的测试通过——零失败覆盖率报告已运行且输出已展示后端与前端覆盖率 ≥ 75%目标 80%无测试反模式Liar、Mirror、Giant、Mockery、InspectorQuality应该修复关键决策点有结构化日志注释解释 WHY 而非 WHAT无过度工程没有 1–2 个琐碎函数单独成文件的文件未延续遗留坏模式Pre-CommitLinter 已对所有改动文件运行——零错误Formatter 已对所有改动文件运行——零 diff类型检查器已运行如适用——零错误这份Pre-Commit清单在 Langflow 仓库中有完整的工具链对应物恰好构成对模板第 12 节最有力的注脚。.pre-commit-config.yaml 中挂着的钩子包括ruff check --fix与ruff format对应 Linter/Formatter 零错误零 diff、detect-secrets对应无硬编码密钥、biome check 与 staged 的 no-any 检查对应前端强类型、以及一批 Langflow 自研检查脚本——如check_component_env_writes.py组件禁止写os.environ呼应可变共享状态是危险、Alembic 迁移的 Expand-Contract 校验等。评审 Skill 中的Pre-Commit Verification一节则把它变成评审动作make format_backend先格式化再评审避免格式噪音掩盖真实改动、make lintlint 期发现的类型错误比生产崩溃便宜一个数量级、make unit_tests失败测试意味着改动破坏了既有行为调查是代码错还是测试错。如何把这份模板落到自己的项目从 Langflow 的实践看把全文 12 节串起来读AGENTS-example.md实际上给出了一条可复制的落地路径而 Langflow 仓库本身就是它的示范工程模板先行标注示例身份。仓库根目录放 AGENTS-example.md显式声明Use at your own risk采纳前请适配避免它被误当成项目强制规范适配层注入领域细节。docs/agents/ 下的 PHILOSOPHY / ARCHITECTURE / TESTING 等文档保留了模板的骨架权衡、分层、对抗性测试、检查清单但把通用规则替换成了可判定的项目事实单向依赖图、组件版本兼容契约file_names_mapping、避免 mock策略、make unit_tests命令工具链兜底强制。pyproject.tomlruffselect [ALL]、120 行宽、pytest marker 与 90s 超时、codecov.yml分组件的覆盖率目标与阈值、.pre-commit-config.yamlruff/biome/detect-secrets/迁移校验钩子把软规则变成提交前自动执行的硬门禁评审 Agent 消费同一套规则。.agents/skills/backend-code-review/SKILL.md 将模板的规则500 行上限、75%/80% 覆盖率、七大测试反模式、PII 零容忍转写成带 Critical/Suggestion/Nit 分级输出格式的评审 Skill让人工评审与 AI 评审共用同一把尺子。需要强调的适用前提该模板自称语言无关、框架无关其表格中的命令pytest/Jest/Vitest与类名如Component是示意性的具体阈值500 行、75% 覆盖率、~4 个注入依赖上限是经验性指南而非行业标准采纳时应以团队现状校准——正如 Langflow 把整体覆盖率目标设为渐进式的 55%/60%/10%而把 75% 底线只施加于新交付的代码。模板结尾的三句话可以作为收尾原则拿不准时选择简单权衡时遵循优先级先正确后优化永远可测。【免费下载链接】langflowLangflow is a powerful tool for building and deploying AI-powered agents and workflows.项目地址: https://gitcode.com/GitHub_Trending/la/langflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Langflow AGENTS-example.md 解析：一份面向 AI 编码代理的开发规范模板，从权衡优先级到交付前检查清单
Langflow AGENTS-example.md 解析一份面向 AI 编码代理的开发规范模板从权衡优先级到交付前检查清单【免费下载链接】langflowLangflow is a powerful tool for building and deploying AI-powered agents and workflows.项目地址: https://gitcode.com/GitHub_Trending/la/langflowAGENTS-example.md是 Langflow 仓库根目录提供的一份语言无关、框架无关的开发标准示例模板定义了从核心理念、设计原则、代码质量、架构分层到测试、评审与交付前检查的完整工程规范。本文以该模板为骨架逐节拆解其规则体系并结合 Langflow 仓库中的实际配置ruff、pytest、pre-commit、codecov与配套的docs/agents/文档、后端代码评审 Skill展示这份模板在真实项目中如何被适配、落地与强制执行帮助读者掌握为 AI 编码代理编写可执行开发规范的方法。模板的定位为什么 Langflow 需要一个 AGENTS-example.mdLangflow 仓库中存在多份面向 AI 编码代理coding agent的指引文件分工明确AGENTS.md项目级代理指引描述项目概览、前置条件Python 3.10–3.14、uv、Node.js与常用命令make init、make unit_tests、make alembic-revision等CLAUDE.md说明本项目采用 AGENTS.md 作为向 AI 代理提供上下文的标准通过AGENTS.md导入指令让 Claude Code 自动加载AGENTS-example.md本文主角——一个标注为 EXAMPLE 的参考模板作者明确提示使用需谨慎Use at your risk建议在采纳前先按项目需要适配docs/agents/PHILOSOPHY.md、docs/agents/ARCHITECTURE.md、docs/agents/TESTING.md 等Langflow 团队将模板思想适配到本项目后的实际产出如十项项目哲学、单向依赖边界、组件测试基类.agents/skills/backend-code-review/SKILL.md一个直接消费该模板规则的评审 Skill其中明确引用了 per AGENTS-example.md 的文件行数限制并把模板中的测试反模式Liar、Mirror、Giant、Mockery……逐条写进了评审规则。可以看出Langflow 的用法是模板提供通用规则骨架项目文档注入领域细节工具链Skill/pre-commit负责强制检查。这种模板 适配 执行的三层结构是本文解读该模板的主线。核心理念权衡优先级与基本规则第 1 节模板开宗明义地给出了冲突发生时的权衡优先级Trade-off Priority正确性Correctness—— 代码做它该做的事简洁与可读性Simplicity and readability—— 代码易于理解可测试性Testability—— 代码易于测试性能Performance—— 代码足够快抽象与复用Abstraction and reuse—— DRY。这个排序的潜台词是性能排第 4、抽象排第 5意味着先写对再写快最后才谈优雅。模板结尾也再次强调当拿不准时选择简单当权衡发生时遵循第 1 节的优先级。先构建正确性之后再做优化永远保持可测试。与之配套的基本规则Ground Rules共有五条修改前先阅读并理解现有代码遵循项目既有的模式与约定需求含糊时先提问再写代码优先增量交付先核心逻辑再边界情况最后打磨不过度工程化为今天的需求而建不为假想的未来而建。Langflow 自身的项目哲学文档 docs/agents/PHILOSOPHY.md 正是这种先问该不该做再问怎么做思路的产物其中第 11 条信条要求没有证据证明改动有效就不算修复先复现失败、再证明修复消除了它与模板中需求含糊时先提问一脉相承。设计原则SOLID、DRY、KISS、YAGNI第 2 节SOLID附常见误区的实现版解释模板没有停留在 SOLID 的口号上而是为每条原则配了规则 常见错误两列的表格原则规则常见误区SRP单一职责每个类/函数/文件只有一个变化理由。需要用到和/或来描述它时就该拆分把 SRP 误解为一个类一个函数。SRP 指的是一个变化轴OCP开闭原则通过写新代码而非改旧代码来增加行为在预期变化的地方用多态或策略模式过早抽象导致的过度工程。OCP 只适用于有证据表明需求会变化的地方LSP里氏替换子类必须遵守父类契约is-a 关系不严格时优先组合而非继承重写父类方法却直接抛NotImplementedError或什么都不做ISP接口隔离定义小而面向角色的接口客户端只依赖它用到的方法创建一个含 15 方法的上帝 service接口DIP依赖倒置在模块边界依赖抽象而非具体实现领域逻辑永远不 import 基础设施把 DIP 等同于用依赖注入就行。DIP 是反转源码依赖的方向值得注意的是 Langflow 的架构文档 docs/agents/ARCHITECTURE.md 将 DIP 落成了可检查的硬规则依赖图只能单向流动langflow → langflow-base → lfxlfx禁止 importlangflow.*并给出反例——在src/lfx/中from langflow.services.deps import session_scope 是违规写法正确做法是在lfx内定义接口、由应用层注入实现。这正是模板中依赖倒置从概念到边界的典型适配。DRY三条红线只有当完全相同的业务规则在 3 处以上重复时Rule of Three才抽取共享逻辑配置、常量、schema 定义保持单一事实来源宁可重复也不要错误的抽象。两段看起来相似但服务于不同业务目的的代码不是重复——强行合并会制造意外的耦合。错误的抽象被明确定义为过早泛化、目的不清、把无关关注点耦合在一起。KISS 与 YAGNI反过度工程的量化口径选择满足当前需求的最简实现标准库优先于自造轮子一次普通的函数调用胜过元编程只需要数据分组时字典胜过类不要以防万一地引入设计模式、抽象或框架只有存在具体的当前需求时才实现功能至少有两个具体用例之前不要搭通用/可扩展框架定期删除投机性代码和无用的 feature flag三行相似代码优于一个过早的抽象。代码质量命名、类型、不可变性与函数设计第 3 节命名规则名字应揭示意图回答它为什么存在、它做什么函数用动词get、create、update、delete、validate、format、parse布尔量用前缀is、has、can、should除非业界通用id、url、api否则不用缩写禁用泛化命名data、result、obj、thing、temp、misc、utils名字中不出现 and、or、then——出现即暗示承担了多个职责。这套命名规则在 Langflow 的评审 Skill .agents/skills/backend-code-review/SKILL.md 中被逐条复刻为检查项Functions should use verbs (get,create,validate). Booleans should use prefixes (is_,has_,can_,should_)说明它已超出示例范畴成为实际评审依据。强类型、不可变性与早返回强类型处处使用强类型避免any/object/dynamic/Object公共函数必须有带类型的参数与返回值不许为了编译通过而强转any。不可变默认不可变const、readonly、final、frozen、tuple、frozenset转换函数返回新对象而非原地修改绝不向外暴露可变内部集合只返回副本或只读视图函数内部的可变局部变量没问题——危险的是可变共享状态。早返回与守卫子句在函数顶部校验前置条件并尽早 return/throw通过取反条件、提前返回来降低嵌套让快乐路径停留在最低缩进层级。无魔法值重复出现的数字和字符串抽成命名常量用描述性变量名替代内联字面量。注释不注释显而易见的代码注释只解释WHY绝不解释WHAT不留注释掉的代码那是版本控制的工作TODO 注释必须带 ticket 引用。函数保持短小、单一抽象层级一个函数做一件事做两件事就拆分不用切换行为的布尔参数而是拆成两个具名函数每次改动都清除死代码和未使用的 import。从仓库的 lint 配置看这些规则有工具兜底pyproject.toml 中 ruff 配置select [ALL]、line-length 120、pydocstyle.convention google即几乎启用全部 lint 规则族并用 Google 风格 docstring 约定约束注释。架构分层职责、依赖注入与 DDD 的适用边界第 4 节关注点分离领域、应用、基础设施三层关注点必须分离领域/业务逻辑对框架、数据库、HTTP 层的 import 数量必须为零副作用I/O、日志、指标留在系统边缘业务逻辑保持纯粹层与层边界上使用 DTO 或值对象——永远不要把 ORM 模型或 HTTP 请求对象传进业务逻辑。分层职责表模板用一张 CAN / CANNOT 表格把五类层的边界钉死层可以不可以Handler/Controller接收输入、委派给 service、返回输出包含业务逻辑、直接调数据库Service/Orchestrator协调操作、执行业务规则感知 HTTP/传输细节、直接执行 SQLRepository/Data Access执行查询、映射数据做业务决策、调用外部 APIHelper转换数据、校验、格式化产生副作用、做 I/O、维护状态External Client与外部服务通信包含业务逻辑、访问数据库Langflow 的 docs/agents/ARCHITECTURE.md 给出了这张表的项目化版本——Service vs Utility vs Component三分类Service继承services/base.Service、经services/factory.py注册、有生命周期与共享连接的单例、Utility无共享状态、无生命周期的纯/近纯函数放helpers/或lfx/utils/、Component画布上用户可见的节点子类。它甚至点破了模板隐含的陷阱MyHelperService这种其实只是一堆函数的 service 是坏味道——工具函数就该是函数不该套 service 壳。依赖注入的五条细则通过构造函数或方法参数注入依赖让所有依赖显式化注入的是 I/O 边界数据库、HTTP 客户端、文件系统、时钟使它们在测试中可替换组合根composition root留在应用入口与业务逻辑分离一个类需要注入超过 ~4 个依赖时说明它职责过载应拆分只注入有副作用或随环境变化的东西纯工具函数不需要注入。DDD仅在值得时应用模板对领域驱动设计持谨慎态度仅当领域复杂度确凿地证明有必要时才引入 DDDEntity、Value Object、Aggregate 只在真正创造价值时使用错误与不变量也应建模为领域的一部分。这与 Langflow 哲学第 2 条每个后端能力必须落到画布上如果不能被非 Python 用户以组件形式接线它属于 SDK 而非平台的克制气质一致——先问值不值再谈怎么建。文件结构行数上限、职责分文件与命名禁区第 5 节单文件生产代码上限指标指南代码行数不含 import、类型定义、文档~500 行到 ~530 可接受600 是红旗承担不同职责的函数最多5 个承担相同职责同前缀的函数最多10 个文件内主类1 个小型相关类异常、DTO、枚举5 个且同类型Langflow 评审 Skill 对这一节做了显式背书生产文件超过 ~500 行……600 行应视为红旗……测试文件超过 ~1000 行应按逻辑分组拆分per AGENTS-example.md并解释了 500 行阈值背后的理由行数越大的文件缺陷率越高、评审越慢且是多重职责SRP 违规的信号。单职责文件与一句话测试每个文件必须有一个存在理由和一个变化理由。判据是一个测试能否不用和/或用一句话描述这个文件的用途按职责前缀分文件函数必须按职责类别分组不同前缀的函数不允许共存于同一文件职责函数前缀对应文件Types/Models类型定义、接口、无逻辑的类{feature}_typesConstantsMAX_*、DEFAULT_*、枚举{feature}_constantsValidationvalidate*、check*、is_valid*validationFormattingformat*、build*、serialize*、to_*formattingParsingparse*、extract*、from_*parsingExternal callsfetch*、send*、call*、request*{service}_clientData accesssave*、load*、find*、delete*、query*{feature}_repositoryOrchestration主入口、协调{feature}_serviceHandlers端点、控制器、视图{feature}_handler反过度拆分与命名禁区不要把 1–2 个合计不到 20 行的琐碎函数拆成独立文件私有辅助函数_func留在使用它的文件里一行工具函数不单独成文件拆分时机 出现清晰、可复用的职责合并时机 拆分只增加复杂度而无收益永远不用泛化文件名的独立文件utils、helpers、misc、common、shared。评审 Skill 给出的解释是叫utils.py的文件会在几个月内变成 50 个函数的垃圾场——每个函数组应放进以职责命名的文件formatting.py、validation.py。模板最后给出一张标准模块结构图feature/ ├── {feature}_service # Orchestration ├── {feature}_types # Type definitions ├── {feature}_constants # Constants and enums ├── helpers/ │ ├── validation # ONLY validation functions │ ├── formatting # ONLY formatting functions │ └── parsing # ONLY parsing functions ├── services/ │ └── {external}_client # ONLY external API communication ├── repositories/ │ └── {feature}_repository # ONLY data persistence └── handlers/ └── {feature}_handler # ONLY request handling错误处理错误是 API 契约的一部分第 6 节模板给出七条错误处理铁律显式处理预期错误零静默失败不用泛型异常Exception、Error、object使用领域相关错误类型抛出/返回的错误必须带上下文什么失败、什么输入导致的、如何修复;错误是 API 契约的一部分在系统边界校验输入非法数据快速失败区分可恢复错误与致命异常绝不静默地修正非法输入——用清晰消息拒绝它。配套的正反例代码# BAD try: result do_something() except: pass # GOOD try: result do_something() except ValidationError as e: logger.warning(Validation failed, extra{error: str(e), field: e.field}) raise DomainError(fInvalid input: {e.field}) from e要点在于 GOOD 写法做了三件事捕获具体异常类型、把失败记入结构化日志带field上下文、以raise ... from e保留异常链——而不是吞掉异常假装一切正常。安全默认拒绝与边界校验第 7 节模板的安全清单可以归纳为四组输入与信任边界在边界处净化并校验所有用户/外部输入永远不信任系统边界之外的数据使用白名单allowlist而非黑名单——默认拒绝只接受已知安全的模式复杂结构用 schema 校验库Pydantic、zod、JSON Schema不手写校验服务端校验永远不可省略——客户端校验只是 UX 便利不是安全措施。密钥管理密钥不进代码使用环境变量或 secret manager不允许硬编码 API key、token、密码。数据访问与错误输出SQL 一律参数化查询禁止字符串拼接面向最终用户的错误消息不暴露内部细节。测试数据测试中使用伪造/匿名数据绝不使用真实用户数据。在 Langflow 仓库中密钥不进代码这条规则由工具链闭环执行.pre-commit-config.yaml 配置了detect-secrets钩子以.secrets.baseline为基线扫描评审 Skill 也把硬编码密钥列为 Critical 级发现项。可观测性结构化日志、级别与 PII 零容忍第 8 节日志原则使用结构化日志key-value / JSON而非格式化字符串在关键决策点与边界处打日志而不是在紧循环内部日志应包含操作名、相关 ID、结果成功/失败、必要时耗时全代码库保持字段名一致。日志级别级别使用场景ERROR有东西坏了需要人工介入WARN降级但可自恢复INFO重要的业务事件DEBUG诊断细节生产环境关闭PII 零容忍绝不记录邮箱、用户名、手机号、住址、token、密码允许的标识符auth_id、user_id、internal_idprint()/console.log()不得携带用户数据——它们会流向生产日志。Langflow 的评审 Skill 把这一节细化到了具体实现层面统一使用lfx.log.logger的异步日志方法adebug、ainfo、awarning、aerror、aexception禁用print()与标准库logging允许的 ID 进一步收敛为user_id、flow_id、session_id异常输出统一用{e!s}表示法。测试测试代码就是生产代码第 9 节模板在此节的立场很强硬Test code is production code.它接受同样的打磨、评审与质量标准。核心原则为所有核心逻辑写单元测试遵循 AAAArrange-Act-Assert结构一个测试一个 act、一个逻辑断言测试必须相互独立、确定性、不依赖执行顺序Mock 或 fake 掉所有外部依赖DB、API、文件系统、时间、随机性测试命名清晰should_[expected]_when_[condition]。不仅要验证还要进攻这是本模板最有辨识度的部分。模板明确指出快乐路径测试只是地基单独的快乐路径测试是不够的。必须写主动进攻代码、寻找缺陷的对抗性测试意外的输入类型None、、[]、{}、0、-1边界值最大 int、最大长度、恰好等于上限、超过上限一格畸形数据缺字段、多字段、错误类型、非法格式错误状态依赖失败时会发生什么验证不该发生的事被禁止的状态被正确拒绝错误消息与类型不只验证它失败了还要验证它如何失败。并给出两条纪律基于需求/规格写测试而不是照抄源码当前的行为——这是捕捉代码偏离预期型 bug 的唯一手段测试失败时先问代码是不是错了而不是默默改断言去迁就现状——不理解原因就改断言是被禁止的。测试文件规则指标指南每文件行数~1000 行指南——超过可考虑拆分但覆盖单一模块时非强制每文件测试数无硬性上限——只在覆盖无关行为时才拆分SetupArrange每测试~20 行上限超出则抽取为 helper/factory原则是按逻辑边界拆分测试文件而不是按任意行数一个文件对应一个模块/服务即使 800 行也完全没问题。覆盖率80% 目标75% 底线目标 80%最低可接受 75%低于 75% 视为任务未完成重点盯分支覆盖if/else两侧、所有catch块而非仅仅是行覆盖没有断言的高覆盖率毫无价值——每个测试至少有一个有意义的断言覆盖率必须实际运行并展示后端和前端都要。模板给出的三类运行命令# Python pytest tests/your_tests.py --covsrc/module_under_test --cov-reportterm-missing --cov-branch -v # JavaScript/TypeScript (Jest) npx jest tests/your_tests.test.ts --coverage --collectCoverageFromsrc/module/**/*.{ts,tsx} # JavaScript/TypeScript (Vitest) npx vitest run tests/your_tests.test.ts --coverage所有创建的测试必须通过零失败、零异常禁止禁用/跳过/删除测试来掩盖失败禁止留下以后再修的测试覆盖率不足 75% 就继续补测试、重跑直到达标。不该测什么简单 getter/setter/trivial mapper 不值得测实现细节方法调用顺序、内部状态应该测行为来替代不要用无意义断言堆覆盖率。七大测试反模式禁止反模式问题The Liar骗子测试通过但没有验证它声称要验证的行为The Mirror镜子测试读源码然后断言代码恰好做了什么——零 bug 产出The Giant巨无霸50 行 setup、多个 act、几十个断言——应拆成 5 个独立测试The Mockery陪练mock 多到测试实际只测了 mock 的搭建过程The Inspector窥探者与实现细节耦合任何重构都把它打碎The Chain Gang连环犯测试依赖执行顺序或共享可变状态The Flaky飘忽者不改代码时有时过有时挂结合仓库实际可以看到这套规范的适配版取舍docs/agents/TESTING.md 针对模板中mock 掉所有外部依赖一条做了项目级修正——Langflow 明确避免 mock、优先打真实依赖因为mock 通过、生产失败曾让团队付出多个发布周期的代价mock 只保留给 LLMMockLanguageModel与真正不稳定且与被测逻辑正交的依赖需要凭据的测试打pytest.mark.api_key_required交给 CI 门控。而 codecov.yml 揭示了另一个现实仓库当前的整体覆盖率目标backend 55%、lfx 60%、frontend 10%、patch 40%是渐进式改进的定位与模板新代码 80%/75%的绝对要求并存——前者管存量大盘后者管每次新增的交付质量。模板命令在 Langflow 中的对应物是 AGENTS.md 中的make unit_tests并行、make unit_tests asyncfalse串行、uv run pytest path/to/test.pypytest 的 markerapi_key_required、security、real_services等统一声明在 pyproject.toml 的[tool.pytest.ini_options]中。代码评审Blocker 优先的评审顺序第 10 节模板定义了评审的固定优先级先处理阻断项安全与 PII—— 日志无 PII、无硬编码密钥、输入有校验DRY—— 无重复的类型、类、函数或逻辑文件结构—— 行数上限被遵守、职责已分离架构—— 单一职责、分层正确代码质量—— SOLID、强类型、错误处理测试—— 快乐路径与对抗性测试兼备、覆盖率达标可观测性—— 结构化日志、无 PII。针对测试的四个灵魂拷问是否同时有快乐路径测试与对抗性测试如果有人改坏了逻辑这些测试能否抓住回归是否存在没被覆盖的边界情况或失败模式如果我删掉一行业务逻辑是否至少有一个测试会失败对遗留代码的态度是不传染不延续坏模式即使周围代码很烂新代码也要写好的不未经评审就从遗留代码复制粘贴在可能的范围内把新代码与遗留隔离。Langflow 的 docs/agents/ARCHITECTURE.md 对这一点有精确表述langflow/base/是遗留目录不要再往里面加东西——新共享原语一律进src/lfx/src/lfx/base/。文档C4 分级与功能文档必备章节第 11 节何时写文档功能实现完成之后再生成功能文档文档与代码同仓存放Markdown使用通用语言ubiquitous language——文档、代码、沟通中使用同一套术语。C4 文档分级级别读者内容Context (L1)产品/干系人系统在其环境中的位置Container (L2)两者应用、数据库、队列Component (L3)工程团队内部服务细节功能文档的八个必备章节Overview—— 摘要、业务背景、限界上下文通用语言术语表—— 领域术语并附代码引用领域模型—— 聚合、实体、值对象、事件行为规格—— Gherkin 场景快乐路径、边界、错误架构决策记录ADR—— 上下文、决策、后果技术规格—— 依赖、API 契约、错误码可观测性—— 指标、日志、仪表盘部署与回滚—— feature flag、迁移、回滚预案。交付前检查清单代码出门前的最后一道闸第 12 节模板要求交付任何代码前逐项验证全部清单项。Critical阻断项任何日志、打印、webhook 消息中无 PII代码中无密钥或凭据无重复的类型、类或逻辑DRY无生产文件超过 ~500 行 / 测试文件超过 ~1000 行同一文件内无混合职责前缀的函数所有用户输入在系统边界被校验Important必须修复每个文件/函数单一职责恰当的错误处理无静默失败、错误信息有意义强类型无any、object、dynamic类型放专属 types 文件、常量放专属 constants 文件领域逻辑独立于框架/基础设施Testing强制所有核心逻辑有单元测试快乐路径与对抗性测试同时存在所有创建/修改的测试通过——零失败覆盖率报告已运行且输出已展示后端与前端覆盖率 ≥ 75%目标 80%无测试反模式Liar、Mirror、Giant、Mockery、InspectorQuality应该修复关键决策点有结构化日志注释解释 WHY 而非 WHAT无过度工程没有 1–2 个琐碎函数单独成文件的文件未延续遗留坏模式Pre-CommitLinter 已对所有改动文件运行——零错误Formatter 已对所有改动文件运行——零 diff类型检查器已运行如适用——零错误这份Pre-Commit清单在 Langflow 仓库中有完整的工具链对应物恰好构成对模板第 12 节最有力的注脚。.pre-commit-config.yaml 中挂着的钩子包括ruff check --fix与ruff format对应 Linter/Formatter 零错误零 diff、detect-secrets对应无硬编码密钥、biome check 与 staged 的 no-any 检查对应前端强类型、以及一批 Langflow 自研检查脚本——如check_component_env_writes.py组件禁止写os.environ呼应可变共享状态是危险、Alembic 迁移的 Expand-Contract 校验等。评审 Skill 中的Pre-Commit Verification一节则把它变成评审动作make format_backend先格式化再评审避免格式噪音掩盖真实改动、make lintlint 期发现的类型错误比生产崩溃便宜一个数量级、make unit_tests失败测试意味着改动破坏了既有行为调查是代码错还是测试错。如何把这份模板落到自己的项目从 Langflow 的实践看把全文 12 节串起来读AGENTS-example.md实际上给出了一条可复制的落地路径而 Langflow 仓库本身就是它的示范工程模板先行标注示例身份。仓库根目录放 AGENTS-example.md显式声明Use at your own risk采纳前请适配避免它被误当成项目强制规范适配层注入领域细节。docs/agents/ 下的 PHILOSOPHY / ARCHITECTURE / TESTING 等文档保留了模板的骨架权衡、分层、对抗性测试、检查清单但把通用规则替换成了可判定的项目事实单向依赖图、组件版本兼容契约file_names_mapping、避免 mock策略、make unit_tests命令工具链兜底强制。pyproject.tomlruffselect [ALL]、120 行宽、pytest marker 与 90s 超时、codecov.yml分组件的覆盖率目标与阈值、.pre-commit-config.yamlruff/biome/detect-secrets/迁移校验钩子把软规则变成提交前自动执行的硬门禁评审 Agent 消费同一套规则。.agents/skills/backend-code-review/SKILL.md 将模板的规则500 行上限、75%/80% 覆盖率、七大测试反模式、PII 零容忍转写成带 Critical/Suggestion/Nit 分级输出格式的评审 Skill让人工评审与 AI 评审共用同一把尺子。需要强调的适用前提该模板自称语言无关、框架无关其表格中的命令pytest/Jest/Vitest与类名如Component是示意性的具体阈值500 行、75% 覆盖率、~4 个注入依赖上限是经验性指南而非行业标准采纳时应以团队现状校准——正如 Langflow 把整体覆盖率目标设为渐进式的 55%/60%/10%而把 75% 底线只施加于新交付的代码。模板结尾的三句话可以作为收尾原则拿不准时选择简单权衡时遵循优先级先正确后优化永远可测。【免费下载链接】langflowLangflow is a powerful tool for building and deploying AI-powered agents and workflows.项目地址: https://gitcode.com/GitHub_Trending/la/langflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考