开发规范（Development Standards）

开发规范（Development Standards）

概念解释

开发规范是一套约束团队成员"怎么写代码、怎么管 Prompt、怎么打版本号、怎么写文档"的标准化规则。它的作用类似于建筑施工图里的"制图标准"：不同工程师画出来的图纸，线型、符号、比例尺都一样，任何人拿到都能看懂。

传统软件开发已经有成熟的代码规范（如 PEP 8、ESLint），但 Agent 应用有一个独特问题：Prompt 也是"代码"。一个系统 Prompt 的措辞微调，可能导致 LLM 输出质量大幅波动。如果 Prompt 没有版本控制，出问题后既无法定位原因，也无法回滚。因此，Agent 开发规范比传统开发规范多了一个核心维度——Prompt 管理规范。

开发规范不是"锦上添花"的事情。在 1-2 人的原型阶段，没有规范也能活；但当团队超过 3 人、或者项目进入生产环境后，没有规范的项目会陷入"改一处、崩三处"的维护泥潭。规范的本质是把隐性的个人习惯变成显性的团队契约，让代码审查、自动化工具、新人上手都有据可依。

关键结构

Agent 开发规范由四个维度组成，每个维度解决一类一致性问题：

维度 1：代码规范

代码规范定义了源代码的书写格式，包括缩进方式、命名约定、行长限制、导入排序等。以 Python 为例，PEP 8 是官方推荐的风格指南，规定了 4 空格缩进、snake_case 函数命名、79 字符行长等。

代码规范的执行不靠人工盯，而是靠 Lint 工具（代码检查器）自动化。常见的 Python Lint 工具对比：

• Ruff：用 Rust 编写，速度比 Flake8 快 10-100 倍，集成了 Flake8 大部分规则和 isort 功能，是 2025 年后新项目的首选
• Flake8：结合 pycodestyle + PyFlakes + mccabe，是 Python 社区最经典的选择
• Pylint：功能最全面，支持高度定制化规则，但也最"啰嗦"

Lint 工具通常在三个阶段执行：开发者本地运行、Git pre-commit hook 自动拦截、CI/CD 流水线最终把关。

维度 2：Prompt 管理规范

Agent 应用的核心逻辑内化在 Prompt 中。传统软件改一行代码，只影响那行代码的逻辑；而改 Prompt 里的一个词，可能让 LLM 的整个输出行为发生变化。Prompt 管理规范的核心原则：

• 唯一标识：每个 Prompt 有唯一 ID（如 agent.classify.system_v2）
• 版本追踪：每次修改记录变更内容和原因（What Changed + Why Changed）
• 效果绑定：每个版本关联评测结果（如准确率、误拒率）
• 回滚能力：发现新版质量下降时，能一条命令切回旧版

维度 3：版本号规范

采用语义化版本（Semantic Versioning，SemVer），格式为 MAJOR.MINOR.PATCH：

• MAJOR（主版本号）：不兼容的 API 变更。例如 Agent 的输入输出格式改了，调用方必须改代码适配
• MINOR（次版本号）：向下兼容的功能新增。例如新增一个工具，不影响已有调用
• PATCH（修订号）：向下兼容的 Bug 修复

SemVer 的价值在于版本号本身携带信息。用户看到 1.2.3 -> 2.0.0，立刻知道"有不兼容变更，需要检查代码"；看到 1.2.3 -> 1.2.4，知道"这是个安全的小修复"。

维度 4：文档规范

文档规范的核心是"文档即代码"（Docs as Code）：文档存放在代码仓库中，与代码一起版本控制，确保同步更新。包括：

• 格式统一：全部使用 Markdown，确保跨平台渲染一致
• 结构标准化：API 文档必须包含功能说明、参数说明、返回值、异常处理、使用示例
• CHANGELOG：遵循 Keep a Changelog 格式，按 Added / Changed / Fixed / Removed 分类记录每个版本的变更

核心原理

原理说明

开发规范的运作逻辑是"规则定义 -> 工具自动执行 -> 流水线强制拦截"的三层保障机制：

1. 规则定义层：团队讨论并确定各维度的规范细则，写入配置文件（如 .flake8、ruff.toml）和规范文档
2. 工具执行层：Lint 工具、Formatter、版本管理脚本在开发者本地自动检查和修复，pre-commit hook 在提交时拦截不合规代码
3. 流水线强制层：CI/CD 在 Pull Request 阶段再次运行全量检查，不合规的代码无法合并到主分支

这三层的关系是逐步收紧的：本地工具提供即时反馈（秒级），pre-commit 提供提交前拦截（秒级），CI/CD 提供最终门禁（分钟级）。这样设计的好处是：开发者能在最早的阶段发现问题，而不是等到代码审查时才被打回。

对于 Prompt 规范，工作机制类似但有差异：Prompt 的"Lint"不是检查语法格式，而是检查结构完整性（是否有系统提示、是否有输出格式约束）和效果指标（通过评测集自动跑分）。

Mermaid 图解

规则定义层的四个维度分别输出配置文件和模板，工具执行层用这些配置在本地进行自动检查，流水线强制层作为最终门禁确保不合规代码无法进入主分支。未通过检查的代码会被打回到工具执行层重新修复，形成闭环。

运行示例

以下伪代码展示 Prompt 版本管理的核心机制：每个 Prompt 有唯一 ID，每次修改自动递增版本号，并记录变更原因和评测结果。

# Prompt 版本管理的核心机制示例（伪代码）

class PromptVersion:
    """一个 Prompt 版本的最小结构"""
    def __init__(self, prompt_id: str, version: str, content: str,
                 change_log: str, eval_score: float = None):
        self.prompt_id = prompt_id    # 唯一标识，如 "agent.classify.system"
        self.version = version        # 语义化版本号，如 "v1.2.0"
        self.content = content        # Prompt 文本内容
        self.change_log = change_log  # 变更说明（What + Why）
        self.eval_score = eval_score  # 评测得分（可选）


class PromptRegistry:
    """Prompt 注册中心：管理所有 Prompt 的版本历史"""
    def __init__(self):
        self.history = {}  # {prompt_id: [PromptVersion, ...]}

    def register(self, prompt_id, content, change_log, eval_score=None):
        """注册新版本，自动递增版本号"""
        versions = self.history.setdefault(prompt_id, [])
        patch = len(versions)
        new_version = PromptVersion(
            prompt_id=prompt_id,
            version=f"v1.0.{patch}",
            content=content,
            change_log=change_log,
            eval_score=eval_score,
        )
        versions.append(new_version)
        return new_version

    def rollback(self, prompt_id, target_version):
        """回滚到指定历史版本（创建新版本，内容复制自目标版本）"""
        for v in self.history.get(prompt_id, []):
            if v.version == target_version:
                return self.register(
                    prompt_id, v.content,
                    change_log=f"回滚至 {target_version}"
                )
        return None

    def get_latest(self, prompt_id):
        """获取最新版本"""
        versions = self.history.get(prompt_id, [])
        return versions[-1] if versions else None

这段代码对应前面"Prompt 管理规范"的三个核心能力：唯一标识（prompt_id）、版本追踪（register 方法自动递增）、回滚能力（rollback 方法创建新版本但复制旧内容）。实际工程中通常用 Git 管理 Prompt 文件，或使用 LangSmith、Humanloop 等专用平台。

易混概念辨析

核心区别：

• 开发规范：覆盖代码、Prompt、版本号、文档四个维度的完整标准体系
• 代码审查：按照规范执行检查的活动，是规范的下游消费者
• CI/CD：自动执行规范检查的基础设施，是规范的自动化载体

适用边界与局限

适用场景

1. 多人协作的 Agent 项目：3 人以上的团队，没有规范会导致代码风格冲突、Prompt 版本混乱、审查效率低下
2. 进入生产环境的 Agent 应用：线上运行的 Agent 需要 Prompt 版本可追踪、可回滚，否则出问题时无法定位和恢复
3. 开源项目治理：贡献者来自不同背景，统一规范是维护代码质量和审查效率的前提
4. 长周期迭代项目：运行超过 6 个月的项目，如果没有规范和变更日志，后续维护者面对的是一团"考古现场"

不适合的场景

1. 一次性原型或 Demo：如果只是验证可行性、写完就扔，花时间建规范的投入产出比不划算
2. 单人独立开发且不打算交接：规范的核心价值是"降低协作摩擦"，单人开发且无交接需求时，个人习惯即可

局限性

1. 初期投入成本不低：选工具、写配置、统一团队认知需要 1-2 周。快速迭代阶段，这段时间可能被视为"浪费"
2. 规范本身需要持续维护：技术栈升级（如 Python 3.9 到 3.13）、工具版本更新、团队规模变化都需要同步更新规范。规范不是写一次就永远有效的
3. Prompt 规范尚无行业标准：代码规范有 PEP 8、Google Style Guide 等成熟标准，但 Prompt 管理规范目前各团队自行摸索，缺乏统一的最佳实践
4. 多语言/多框架项目管理复杂度翻倍：同时使用 Python、TypeScript、Go 的项目，每种语言都需要独立的 Lint 配置和规则集

常见误区

思考题

参考资料

1. PEP 8 -- Style Guide for Python Code. https://peps.python.org/pep-0008/
2. Semantic Versioning 2.0.0（语义化版本规范）. https://semver.org/lang/zh-CN/
3. Keep a Changelog（变更日志规范）. https://keepachangelog.com/zh-CN/
4. Ruff -- An extremely fast Python linter and code formatter. https://docs.astral.sh/ruff/
5. Anthropic Prompt Engineering - Version Management. https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/version-prompts