1. 项目概述为什么我们需要一个“工程化”的AI编码方法论如果你和我一样在过去一两年里深度使用过Claude Code、Cursor或者GitHub Copilot来构建项目你大概率经历过一个令人沮丧的循环项目在Demo阶段跑得飞快代码行云流水感觉生产力爆棚。但当你试图把它推向生产环境或者仅仅是在几周后回头维护时一切都开始崩塌。你发现AI生成的代码逻辑难以理解安全漏洞像地雷一样埋在各个角落依赖管理一团糟整个项目结构脆弱得像用纸牌搭的房子。问题从来不是AI写不出代码而是它在一个真空中写作——它缺乏一个坚实、一致、可理解的上下文基础来构建。这就是bedrock要解决的核心痛点。它不是一个新框架也不是一个神奇的代码生成器。它是一个完整的工程化方法论一套用于智能体工程的“操作系统”。你可以把它理解为在让AI动工之前你必须先铺设好的地基。它涵盖了从项目愿景、设计规范、上下文工程、工作流管理到供应链安全、质量保障、可观测性和长期可持续性的所有层面。最妙的是它提供了一个交互式CLI通过回答十几个问题就能为你生成所有必要的上下文文件并适配你正在使用的任何AI工具Claude、Cursor、Windsurf、Copilot等。简单来说bedrock试图将“氛围编码”从一种依赖灵感和运气的艺术转变为一门可重复、可扩展、生产就绪的工程学科。它承认AI是强大的执行者但人类必须是架构师、审查者和质量守门员。2. 核心理念拆解分形循环与智能体工程2.1 分形循环从周末项目到企业级应用的统一模式bedrock方法论的核心是一个名为“分形循环”的六步流程澄清 - 定义 - 上下文 - 构建 - 验证 - 闭环。这个循环的美妙之处在于它的自相似性。对于一个周末黑客松项目你可能只运行这个循环一次浅尝辄止在两小时内完成。但对于一个生产级的SaaS应用这个循环是递归运行的整个项目运行一次大循环其中的每个核心功能模块运行自己的中循环每个组件甚至每个复杂函数都可能运行一个小循环。这就像观察曼德博集合——无论你放大多少倍看到的都是相似但更精细的结构。为什么这种分形思维至关重要在传统的瀑布或敏捷开发中我们为不同规模的项目设计不同的流程这导致了认知负荷和工具链的碎片化。bedrock提出无论项目大小高质量软件构建的核心心智模型是相同的你必须先想清楚澄清写下来定义让执行者充分理解上下文然后才动手构建最后检查成果验证并总结经验闭环。AI作为执行者尤其依赖前三个步骤的清晰度。模糊的输入必然导致混乱的输出。2.2 智能体工程重新定义人机协作角色“智能体工程”这个术语正如项目所述由Andrej Karpathy在2026年初普及。它精准地描述了bedrock所倡导的协作范式结构化的人机协作其中AI智能体负责实现而人类则牢牢掌握架构设计、代码审查和质量保证的主动权。这彻底颠覆了早期“把需求扔给AI然后祈祷”的用法。在智能体工程范式中人类是产品经理和系统架构师负责定义“做什么”和“为什么这么做”设定不可逾越的边界如技术栈、安全红线、设计规范。AI是高级工程师和快速原型专家在人类设定的清晰边界和丰富上下文中高效地完成“怎么做”的编码工作。人类也是最终的质量关卡AI的输出必须经过人类基于上下文的验证尤其是安全性和架构一致性方面。bedrock提供的所有文件模板——从VISION.md到CONSTITUTION.md再到WORKFLOW/目录下的会话管理文件——本质上都是在为这种新型协作关系建立协议和沟通语言。它确保AI不是在盲目猜测而是在一个精心设计的沙箱中创造。3. 核心目录结构与文件深度解析bedrock的目录结构是其方法论的物理体现。每个文件夹代表软件生命周期中的一个关键层面。让我们深入几个核心目录看看它们如何在实际操作中发挥作用。3.10-vision/在AI动工前人类必须完成的作业这个目录是绝对禁止AI参与的领域。它是项目的“宪法起草会议”决定了项目的根基。SPARK.md这里不是写模糊的“我想做个社交APP”。而是需要清晰定义1具体问题哪个用户群体在什么场景下遇到了什么痛点2目标受众他们是谁有什么技术背景3时机为什么现在是解决这个问题的最好时机4非目标明确本项目不会做什么这能避免范围蔓延。NORTH_STAR.md用一句话概括项目的终极使命。例如“为独立开发者提供一个在48小时内从想法到可部署原型的、安全无忧的AI辅助开发环境。” 所有后续决策都应向这颗“北极星”看齐。SCOPE.md画下硬边界。例如“本项目将始终是一个无服务器优先的后端API服务不会包含任何前端用户界面。”“绝不直接处理用户的支付信息必须集成经过审计的第三方支付网关。” 这些是AI绝对不能触碰的红线。DECISIONS.md架构决策记录。记录每个重大技术选型背后的“为什么”。例如“为什么选择PostgreSQL而非MongoDB——因为我们需要强一致的事务来处理核心业务逻辑。” 这不仅是给未来维护者的文档更是给AI的上下文让它理解现有架构的合理性避免其提出颠覆性但可能破坏性的“优化”建议。实操心得我发现在项目初期花上1-2小时与团队成员或自己激烈辩论并敲定这些文件能节省后期数十小时的返工和解释成本。当AI试图引入一个花哨的新数据库时你可以直接引用SCOPE.md和DECISIONS.md来拒绝而不是陷入技术优劣的无休止讨论。3.22-context/AI的“大脑”与行为准则这是注入到每个AI编码会话中的核心上下文是bedrock的“引擎室”。AGENT.md定义AI的全局行为模式。它不仅仅是“你是一个有帮助的助手”。我通常会把它写成“你是一个思维严谨、追求简洁的外科医生式工程师。在动手写代码前你必须先解释你的实现思路。你偏好小而专注的函数厌恶重复代码。你的首要目标是实现BLUEPRINT.md中定义的功能同时严格遵守CONSTITUTION.md中的所有条款。任何对STACK.md中既定技术的变更都必须先向我提出并征得同意。” 这设定了协作的基调。CONSTITUTION.md项目的最高法律。这里列出绝对不允许违反的规则。例如“宪法第一条所有用户输入在进入数据库查询前必须经过参数化处理或ORM转义禁止任何形式的字符串拼接。”“宪法第二条所有数据库表在创建时必须启用行级安全策略并在SECURITY.md中提供匿名用户测试用例。”“宪法第三条禁止引入package.json或requirements.txt中未预先审核通过的依赖。” 违反宪法的代码将被无条件拒绝。ARCHITECTURE.md系统设计图。用文字和简单的图表如Mermaid但需注意bedrock输出禁用它你可以用文字描述说明数据流、服务边界、组件关系。例如“前端Next.js应用通过API路由调用独立的BFF服务BFF服务与核心PostgreSQL数据库和Redis缓存交互。所有服务间通信必须通过定义在/lib/api-client中的类型安全客户端。”STACK.md明确的技术栈清单。包括语言、框架、主要库及其版本号。例如“前端Next.js 15, React 19, Tailwind CSS 4.0。状态管理Zustand。后端Python 3.12, FastAPI。数据库PostgreSQL 16使用Prisma ORM。” 并注明“此技术栈未经人工审核不得变更。AI若认为有更优选择需在DECISIONS.md中发起讨论。”INTENT.md这是bedrock最具洞察力的文件之一。它记录那些“不那么明显”的决策背后的意图。例如“我们之所以在用户模型中添加一个deactivated_at字段而不是直接删除记录是为了满足欧盟GDPR的‘被遗忘权’审计要求同时保留必要的业务日志。” 当AI或未来的开发者看到这个字段时他们不会觉得奇怪或试图“优化”掉它。.aiignore类似于.gitignore但用于保护敏感信息。必须将包含生产环境密钥、数据库连接字符串、第三方API密钥的任何文件如.env.production,config/prod.yaml列入其中。确保AI在会话中完全无法读取这些内容从源头杜绝泄露风险。3.34-security/与5-quality/从第一天起就为生产环境做准备大多数“氛围编码”项目死于安全漏洞和质量失控。bedrock将这两者视为必须内置的上下文而非事后补丁。SECURITY.md不仅仅是OWASP Top 10的清单。它应该包含针对你特定技术栈的深入指南。例如对于Next.js应用明确说明如何使用next/headers安全地读取cookies如何配置CSP头部如何防止CSRF。对于数据库必须包含RLS策略的有效性验证测试见下文。DEPENDENCIES.md供应链安全手册。这是应对“依赖混淆攻击”和“垃圾包投毒”的关键。规则必须包括1所有依赖必须在package.json中固定主版本号。2AI建议的任何新依赖在运行npm install或pip install之前必须人工在官方仓库npmjs.com, PyPI核实其真实性和最近更新情况。3每次会话开始前运行npm audit --audit-levelhigh或pip-audit并解决所有高危漏洞。4使用package-lock.json或poetry.lock禁止使用^或~进行自动更新。DATABASE.md生产数据库是神圣不可侵犯的。这份文件必须强调“PROD IS SACRED”。它应包含1完整的模式定义和迁移策略。2RLS策略详解及验证脚本。例如一个PostgreSQL验证脚本可能长这样-- 切换到匿名用户角色假设你使用Supabase或类似服务 SET ROLE anon; -- 尝试查询一个受RLS保护的用户表 SELECT * FROM public.users; -- 如果返回任何行说明RLS策略失效必须立即修复。3明确禁止在客户端代码、日志或任何AI可读的文件中出现service_role或具有管理员权限的数据库密钥。TESTING.md倡导“测试优先的提示”。不是让AI先写代码再补测试而是在BLUEPRINT.md中定义功能时就同时描述关键的测试用例和预期边界。例如“用户注册功能应验证邮箱格式拒绝重复邮箱密码需哈希存储。测试用例需包含有效注册、重复邮箱注册、无效邮箱格式、密码强度不足。”4. 实战工作流一个功能从构思到上线的完整循环让我们通过一个具体的例子——为一个SaaS应用添加“团队邀请功能”——来演示bedrock工作流如何运行。4.1 阶段一澄清与定义人类工作更新0-vision/PLAN.md在项目计划中新增“团队协作模块”。创建3-workflow/BLUEPRINT.md这是功能说明书。内容需包括功能概述允许现有团队成员通过邮箱邀请新成员加入团队。用户故事作为团队管理员我希望邀请新成员以便他们能访问团队资源。技术规格后端创建team_invitations表字段id, team_id, email, token, inviter_id, status, expires_at。API端点POST /api/teams/:id/invitations(创建邀请)GET /api/invitations/:token(验证邀请)POST /api/invitations/:token/accept(接受邀请)。前端一个邀请表单一个邀请链接页面一个接受邀请的页面。设计参考附上Figma链接或描述UI组件使用1-design/COMPONENTS.md中的现有组件。安全与合规邀请令牌必须使用加密安全的随机数生成。邀请邮件必须包含取消订阅链接符合CAN-SPAM/GDPR。必须验证被邀请邮箱的域名是否在公司允许列表内参考SECURITY.md。验收标准列出5-7条具体的、可验证的完成标准。4.2 阶段二上下文注入与AI构建启动AI会话打开你的AI编码工具如Cursor。注入上下文Cursor会自动读取项目根目录的.cursorrules文件由bedrockCLI生成。这个文件本质上是2-context/目录下核心文件的精炼汇总确保了AI拥有全部必要的背景知识。开始构建你可以直接将BLUEPRINT.md中的“技术规格”部分复制给AI并附上指令“请根据BLUEPRINT.md和项目宪法实现团队邀请功能。请先给出数据库迁移文件然后是后端API最后是前端组件。每一步请先解释你的实现思路。”迭代与审查AI会生成代码。你的角色是审查架构一致性生成的API结构是否符合ARCHITECTURE.md中定义的模式安全性是否使用了参数化查询生成的邀请令牌是否足够随机RLS策略是否被正确考虑代码质量函数是否足够小且单一是否有明显的重复代码4.3 阶段三验证与闭环运行测试执行AI生成的测试并补充你可能想到的边缘情况测试。安全验证运行DEPENDENCIES.md中要求的审计命令。手动测试RLS尝试用匿名密钥查询team_invitations表应该返回空。更新3-workflow/HANDOFF.md本次会话结束前创建或更新交接文档。记录本次会话实现的功能。做出的关键决策及其原因例如选择使用JWT而非自定义令牌。遇到的任何问题及解决方案。下一步的建议。 这份文档消除了“上下文冷启动”问题。明天你或另一位开发者打开项目阅读HANDOFF.md就能立刻接上。提交代码遵循3-workflow/GIT.md中的提交规范例如feat: add team invitation API and UI。5. 安全实战超越检查清单的有效性验证bedrock的安全哲学是“验证有效性而非存在性”。让我分享几个从痛苦经历中总结的、超越普通检查清单的实战技巧。5.1 数据库行级安全实战陷阱许多教程告诉你“启用RLS”但很少告诉你如何验证它真的在工作。我曾在一个项目中AI生成了看似正确的RLS策略但因为在策略中错误地使用了USING (true)导致所有记录暴露。以下是我们的验证流程现在已写入项目的SECURITY.md创建验证脚本(scripts/verify_rls.sql)-- 假设使用Supabaseanon是匿名角色 \set ROLE anon \set TABLE_NAME your_sensitive_table SELECT :TABLE_NAME as table_name, EXISTS ( SELECT FROM pg_tables WHERE schemaname public AND tablename :TABLE_NAME ) as table_exists, EXISTS ( SELECT FROM pg_policies WHERE tablename :TABLE_NAME AND schemaname public ) as has_rls_policy, (SELECT COUNT(*) FROM public.:TABLE_NAME) as total_rows, (SELECT COUNT(*) FROM public.:TABLE_NAME) as rows_visible_to_anon WHERE current_setting(role) :ROLE;这个脚本会切换到匿名角色然后报告表是否存在、是否有RLS策略、总行数以及匿名用户能看到多少行。理想情况下rows_visible_to_anon应该为0。集成到CI/CD将上述脚本的运行作为CI流水线的一个步骤。任何合并请求如果导致匿名用户可见行数大于0则自动失败。5.2 依赖供应链防御“垃圾包投毒”与幻觉防御AI大约有20%的概率会“幻觉”出不存在的包名例如把lodash写成loadash。攻击者已经批量注册这些常见的拼错包名植入恶意代码等待AI或粗心的开发者上钩。我们的防御策略DEPENDENCIES.md中的强制审核流程任何新增依赖必须由人类在npmjs.com或PyPI上手动搜索确认。检查包的最新更新时间、维护者、下载量、开源仓库链接。一个上周刚创建、零下载量的包是危险信号。使用npm info package-name或pip show package-name查看详细元数据。使用锁定文件和可信仓库强制使用npm ci基于package-lock.json进行安装确保依赖树完全可复现。配置.npmrc将仓库源指向官方源或经过审计的内部镜像禁止从不受信任的源安装。AI提示词强化在AGENT.md中明确加入“在建议任何新的npm或pip包之前你必须声明’我建议添加包X。请注意这是一个外部依赖你需要手动在官方仓库验证其真实性和安全性后再安装。’”5.3 密钥与敏感信息管理最可怕的泄露往往不是黑客攻击而是意外提交。我们的规则立即忽略项目初始化后第一件事就是将.env.local,.env.production,*-config.yaml等文件加入.aiignore和.gitignore。使用环境变量模板创建.env.example文件列出所有需要的环境变量不含真实值并加入2-context/目录确保AI知道需要哪些配置但又接触不到真实值。CI/CD密钥隔离生产环境的部署密钥、数据库连接字符串只存储在GitHub Secrets或类似CI/CD平台中绝不进入代码库。6. 可持续性如何维护一个“氛围编码”诞生的项目这是bedrock最具前瞻性的部分。代码写出来只是开始维护才是真正的挑战。6.1 重新让AI“上车”MAINTAIN.md指南当你几个月后回到一个AI生成的项目如何让AI重新理解上下文MAINTAIN.md提供了“再入职”流程健康检查运行一套标准化的脚本检查依赖漏洞、过时的包、破碎的测试。上下文预热不要直接让AI修改代码。首先要求它“阅读项目的DECISIONS.md、ARCHITECTURE.md和最近5份HANDOFF.md文件然后写一份关于当前系统架构和状态的理解摘要。” 这能测试AI对项目的理解程度。渐进式任务从一个小而明确的修复或功能开始而不是一个大的重构。6.2 安全重构AI代码REFACTOR.md策略AI生成的代码有时会有奇怪的模式或重复。重构是必要的但必须谨慎。黄金法则一次只重构一个清晰定义的、有完整测试覆盖的模块。事前快照在开始重构前确保该模块的所有公开API都有完整的集成测试。如果没有先补测试。保持行为一致重构的目标是提升内部质量可读性、性能、结构而不是改变外部行为。使用差分测试或快照测试来确保。与AI结对将现有的代码和你的重构意图一起发给AI“这是当前的userService模块。我希望将其中的验证逻辑提取到一个独立的validation工具类中同时保持所有现有API的输入输出不变。请帮我规划重构步骤并优先为提取出的新函数编写测试。”6.3 人类交接手册HANDOFF_HUMAN.md如何向一个从未接触过此项目的人类开发者解释这个由AI辅助构建的代码库项目起源简要说明最初的问题、北极星指标。开发哲学解释这是一个“智能体工程”项目AI负责实现人类负责架构和审查。指出关键的上下文文件CONSTITUTION.md,ARCHITECTURE.md。代码库导航指出哪些部分是AI生成的可能风格统一但缺乏深层注释哪些部分是人工精心编写的核心逻辑。工作流说明如何启动开发服务器如何运行测试最重要的是如何与AI协作——即在修改任何东西前先阅读相关的DECISIONS.md和HANDOFF.md记录。“地雷”区域标注那些已知的、棘手但暂时没时间修复的代码区域。7. 工具链集成与自动化设置bedrock的init/setup.pyCLI是其易用性的关键。它通过一系列问题为你生成所有工具的配置文件。7.1 CLI设置流程详解运行python3 init/setup.py后你会被问到大约15个问题项目基本信息名称、简短描述。技术栈选择前端、后端、数据库、云服务商。这决定了STACK.md的内容和示例代码模板。设计风格从预置的几种UI风格如“现代简约”、“企业级”、“活泼创意”中选择或提供你自己的Tailwind配置/色彩体系。这会填充DESIGN.md和AESTHETIC.md。AI工具选择勾选你使用的所有工具可多选。CLI会为每个工具生成对应的配置文件。安全严格等级根据项目类型内部工具、MVP、生产SaaS选择安全级别这会影响SECURITY.md和DEPENDENCIES.md的严格程度。基于你的回答CLI会利用Jinja2模板引擎生成一个完整的、为你项目定制的bedrock目录结构所有文件都已预填充了相关上下文。7.2 生成的文件解析以.cursorrules为例对于Cursor用户会生成一个.cursorrules文件。它不是一个简单的提示词列表而是一个结构化的、引用了其他核心文件的文档。内容大致如下# Project Context Constitution ## Core Principles {{ include_from_file(‘2-context/AGENT.md’) }} ## Project Laws (DO NOT VIOLATE) {{ include_from_file(‘2-context/CONSTITUTION.md’) }} ## Tech Stack (Immutable) - **Frontend**: {{ stack.frontend }} - **Backend**: {{ stack.backend }} - **Database**: {{ stack.database }} - **Key Libraries**: {{ stack.libraries }} *Do not suggest alternatives without explicit user approval.* ## Current Focus We are currently implementing the feature described in: 3-workflow/BLUEPRINT.md Refer to 3-workflow/PLAN.md for the overall project roadmap. ## Code Style - Write small, pure functions. - Prefer async/await over callbacks. - Use the design tokens from 1-design/DESIGN.md for all UI work. - Follow the testing patterns in 5-quality/TESTING.md. ## Security Reminders - All SQL must be parameterized. - RLS must be enabled and tested for new tables. - Audit new dependencies before suggesting npm install.这种生成方式确保了“单一事实来源”。当你更新顶层的CONSTITUTION.md时所有工具的配置文件在下次运行CLI时都会同步更新保持了上下文的一致性。7.3 Web界面包的使用对于使用Claude.ai或ChatGPT Web版“项目”功能的用户bedrock会生成一个context-package/文件夹。这个文件夹包含了一个精简版的、按顺序加载的上下文文件集00-INDEX.md,01-AGENT.md, …。你只需要将这个文件夹整个上传到Web项目的上下文区域AI就能获得一个结构化的、全面的项目背景从而在聊天界面中也能进行高质量的、上下文感知的编码对话。这解决了Web版AI工具上下文碎片化的问题。8. 从理念到实践我的个人经验与避坑指南在过去几个月中我将bedrock方法论应用于两个中型项目和一个快速原型中。以下是一些最宝贵的经验教训经验一不要跳过“愿景”阶段即使它很痛苦。我曾为一个内部管理工具跳过0-vision/直接开始编码。三周后我们陷入了功能蔓延的泥潭因为每个利益相关者对工具的“核心”都有不同理解。被迫回头补做SPARK.md和SCOPE.md时我们才发现最初的目标如此模糊。花2小时争论并写下“非目标”节省了后面200小时的开发时间。经验二INTENT.md是应对“为什么这么蠢”的最佳防御。AI或新队友经常会质疑一些看似不优的设计。例如我们有一个“用户状态”字段用了复杂的枚举ACTIVE,PENDING,SUSPENDED,LEGACY而不是简单的布尔值。在INTENT.md中我们记录了“LEGACY状态用于迁移自旧系统的用户他们需要不同的登录流程。SUSPENDED与PENDING的区别在于前者是管理员手动暂停后者是等待邮箱验证。” 这避免了无数次的重复解释和潜在的“修复”尝试。经验三将安全验证自动化否则会被遗忘。最初我们的RLS验证是手动的。果然在一次紧急功能更新中我们忘了测。直到上线前一天才偶然发现一个数据泄露漏洞。现在我们按照bedrock的建议在4-security/.github/workflows/security.yml中集成了自动化的PostgreSQL测试。每次PR都会在一个临时数据库中创建表、应用RLS策略并以匿名角色运行查询测试。如果返回任何数据CI直接失败。这堵上了人为疏忽的漏洞。经验四HANDOFF.md是时间旅行机器。养成每次编码会话结束前花5分钟写HANDOFF.md的习惯。上周我需要修改一个两个月前由AI实现的、关于文件上传的复杂逻辑。如果没有当时的HANDOFF.md记录着“选择Pre-signed URL而非直接上传至服务器是为了避免后端负载并利用S3的冗余存储”我可能需要半天来重新理解这个决策。有了它我5分钟就进入了状态。最后的建议bedrock不是一个需要全盘接受的教条。从scales/MICRO.md开始。即使只采用AGENT.md、CONSTITUTION.md和PLAN.md这三个文件你也能立刻感受到项目清晰度和AI输出质量的显著提升。它的价值不在于复杂性而在于它强制你思考那些在“氛围编码”的热潮中最容易被忽略却又最为重要的基础问题。
Bedrock：工程化AI编码方法论，从氛围编码到生产就绪
发布时间：2026/7/29 2:34:01
1. 项目概述为什么我们需要一个“工程化”的AI编码方法论如果你和我一样在过去一两年里深度使用过Claude Code、Cursor或者GitHub Copilot来构建项目你大概率经历过一个令人沮丧的循环项目在Demo阶段跑得飞快代码行云流水感觉生产力爆棚。但当你试图把它推向生产环境或者仅仅是在几周后回头维护时一切都开始崩塌。你发现AI生成的代码逻辑难以理解安全漏洞像地雷一样埋在各个角落依赖管理一团糟整个项目结构脆弱得像用纸牌搭的房子。问题从来不是AI写不出代码而是它在一个真空中写作——它缺乏一个坚实、一致、可理解的上下文基础来构建。这就是bedrock要解决的核心痛点。它不是一个新框架也不是一个神奇的代码生成器。它是一个完整的工程化方法论一套用于智能体工程的“操作系统”。你可以把它理解为在让AI动工之前你必须先铺设好的地基。它涵盖了从项目愿景、设计规范、上下文工程、工作流管理到供应链安全、质量保障、可观测性和长期可持续性的所有层面。最妙的是它提供了一个交互式CLI通过回答十几个问题就能为你生成所有必要的上下文文件并适配你正在使用的任何AI工具Claude、Cursor、Windsurf、Copilot等。简单来说bedrock试图将“氛围编码”从一种依赖灵感和运气的艺术转变为一门可重复、可扩展、生产就绪的工程学科。它承认AI是强大的执行者但人类必须是架构师、审查者和质量守门员。2. 核心理念拆解分形循环与智能体工程2.1 分形循环从周末项目到企业级应用的统一模式bedrock方法论的核心是一个名为“分形循环”的六步流程澄清 - 定义 - 上下文 - 构建 - 验证 - 闭环。这个循环的美妙之处在于它的自相似性。对于一个周末黑客松项目你可能只运行这个循环一次浅尝辄止在两小时内完成。但对于一个生产级的SaaS应用这个循环是递归运行的整个项目运行一次大循环其中的每个核心功能模块运行自己的中循环每个组件甚至每个复杂函数都可能运行一个小循环。这就像观察曼德博集合——无论你放大多少倍看到的都是相似但更精细的结构。为什么这种分形思维至关重要在传统的瀑布或敏捷开发中我们为不同规模的项目设计不同的流程这导致了认知负荷和工具链的碎片化。bedrock提出无论项目大小高质量软件构建的核心心智模型是相同的你必须先想清楚澄清写下来定义让执行者充分理解上下文然后才动手构建最后检查成果验证并总结经验闭环。AI作为执行者尤其依赖前三个步骤的清晰度。模糊的输入必然导致混乱的输出。2.2 智能体工程重新定义人机协作角色“智能体工程”这个术语正如项目所述由Andrej Karpathy在2026年初普及。它精准地描述了bedrock所倡导的协作范式结构化的人机协作其中AI智能体负责实现而人类则牢牢掌握架构设计、代码审查和质量保证的主动权。这彻底颠覆了早期“把需求扔给AI然后祈祷”的用法。在智能体工程范式中人类是产品经理和系统架构师负责定义“做什么”和“为什么这么做”设定不可逾越的边界如技术栈、安全红线、设计规范。AI是高级工程师和快速原型专家在人类设定的清晰边界和丰富上下文中高效地完成“怎么做”的编码工作。人类也是最终的质量关卡AI的输出必须经过人类基于上下文的验证尤其是安全性和架构一致性方面。bedrock提供的所有文件模板——从VISION.md到CONSTITUTION.md再到WORKFLOW/目录下的会话管理文件——本质上都是在为这种新型协作关系建立协议和沟通语言。它确保AI不是在盲目猜测而是在一个精心设计的沙箱中创造。3. 核心目录结构与文件深度解析bedrock的目录结构是其方法论的物理体现。每个文件夹代表软件生命周期中的一个关键层面。让我们深入几个核心目录看看它们如何在实际操作中发挥作用。3.10-vision/在AI动工前人类必须完成的作业这个目录是绝对禁止AI参与的领域。它是项目的“宪法起草会议”决定了项目的根基。SPARK.md这里不是写模糊的“我想做个社交APP”。而是需要清晰定义1具体问题哪个用户群体在什么场景下遇到了什么痛点2目标受众他们是谁有什么技术背景3时机为什么现在是解决这个问题的最好时机4非目标明确本项目不会做什么这能避免范围蔓延。NORTH_STAR.md用一句话概括项目的终极使命。例如“为独立开发者提供一个在48小时内从想法到可部署原型的、安全无忧的AI辅助开发环境。” 所有后续决策都应向这颗“北极星”看齐。SCOPE.md画下硬边界。例如“本项目将始终是一个无服务器优先的后端API服务不会包含任何前端用户界面。”“绝不直接处理用户的支付信息必须集成经过审计的第三方支付网关。” 这些是AI绝对不能触碰的红线。DECISIONS.md架构决策记录。记录每个重大技术选型背后的“为什么”。例如“为什么选择PostgreSQL而非MongoDB——因为我们需要强一致的事务来处理核心业务逻辑。” 这不仅是给未来维护者的文档更是给AI的上下文让它理解现有架构的合理性避免其提出颠覆性但可能破坏性的“优化”建议。实操心得我发现在项目初期花上1-2小时与团队成员或自己激烈辩论并敲定这些文件能节省后期数十小时的返工和解释成本。当AI试图引入一个花哨的新数据库时你可以直接引用SCOPE.md和DECISIONS.md来拒绝而不是陷入技术优劣的无休止讨论。3.22-context/AI的“大脑”与行为准则这是注入到每个AI编码会话中的核心上下文是bedrock的“引擎室”。AGENT.md定义AI的全局行为模式。它不仅仅是“你是一个有帮助的助手”。我通常会把它写成“你是一个思维严谨、追求简洁的外科医生式工程师。在动手写代码前你必须先解释你的实现思路。你偏好小而专注的函数厌恶重复代码。你的首要目标是实现BLUEPRINT.md中定义的功能同时严格遵守CONSTITUTION.md中的所有条款。任何对STACK.md中既定技术的变更都必须先向我提出并征得同意。” 这设定了协作的基调。CONSTITUTION.md项目的最高法律。这里列出绝对不允许违反的规则。例如“宪法第一条所有用户输入在进入数据库查询前必须经过参数化处理或ORM转义禁止任何形式的字符串拼接。”“宪法第二条所有数据库表在创建时必须启用行级安全策略并在SECURITY.md中提供匿名用户测试用例。”“宪法第三条禁止引入package.json或requirements.txt中未预先审核通过的依赖。” 违反宪法的代码将被无条件拒绝。ARCHITECTURE.md系统设计图。用文字和简单的图表如Mermaid但需注意bedrock输出禁用它你可以用文字描述说明数据流、服务边界、组件关系。例如“前端Next.js应用通过API路由调用独立的BFF服务BFF服务与核心PostgreSQL数据库和Redis缓存交互。所有服务间通信必须通过定义在/lib/api-client中的类型安全客户端。”STACK.md明确的技术栈清单。包括语言、框架、主要库及其版本号。例如“前端Next.js 15, React 19, Tailwind CSS 4.0。状态管理Zustand。后端Python 3.12, FastAPI。数据库PostgreSQL 16使用Prisma ORM。” 并注明“此技术栈未经人工审核不得变更。AI若认为有更优选择需在DECISIONS.md中发起讨论。”INTENT.md这是bedrock最具洞察力的文件之一。它记录那些“不那么明显”的决策背后的意图。例如“我们之所以在用户模型中添加一个deactivated_at字段而不是直接删除记录是为了满足欧盟GDPR的‘被遗忘权’审计要求同时保留必要的业务日志。” 当AI或未来的开发者看到这个字段时他们不会觉得奇怪或试图“优化”掉它。.aiignore类似于.gitignore但用于保护敏感信息。必须将包含生产环境密钥、数据库连接字符串、第三方API密钥的任何文件如.env.production,config/prod.yaml列入其中。确保AI在会话中完全无法读取这些内容从源头杜绝泄露风险。3.34-security/与5-quality/从第一天起就为生产环境做准备大多数“氛围编码”项目死于安全漏洞和质量失控。bedrock将这两者视为必须内置的上下文而非事后补丁。SECURITY.md不仅仅是OWASP Top 10的清单。它应该包含针对你特定技术栈的深入指南。例如对于Next.js应用明确说明如何使用next/headers安全地读取cookies如何配置CSP头部如何防止CSRF。对于数据库必须包含RLS策略的有效性验证测试见下文。DEPENDENCIES.md供应链安全手册。这是应对“依赖混淆攻击”和“垃圾包投毒”的关键。规则必须包括1所有依赖必须在package.json中固定主版本号。2AI建议的任何新依赖在运行npm install或pip install之前必须人工在官方仓库npmjs.com, PyPI核实其真实性和最近更新情况。3每次会话开始前运行npm audit --audit-levelhigh或pip-audit并解决所有高危漏洞。4使用package-lock.json或poetry.lock禁止使用^或~进行自动更新。DATABASE.md生产数据库是神圣不可侵犯的。这份文件必须强调“PROD IS SACRED”。它应包含1完整的模式定义和迁移策略。2RLS策略详解及验证脚本。例如一个PostgreSQL验证脚本可能长这样-- 切换到匿名用户角色假设你使用Supabase或类似服务 SET ROLE anon; -- 尝试查询一个受RLS保护的用户表 SELECT * FROM public.users; -- 如果返回任何行说明RLS策略失效必须立即修复。3明确禁止在客户端代码、日志或任何AI可读的文件中出现service_role或具有管理员权限的数据库密钥。TESTING.md倡导“测试优先的提示”。不是让AI先写代码再补测试而是在BLUEPRINT.md中定义功能时就同时描述关键的测试用例和预期边界。例如“用户注册功能应验证邮箱格式拒绝重复邮箱密码需哈希存储。测试用例需包含有效注册、重复邮箱注册、无效邮箱格式、密码强度不足。”4. 实战工作流一个功能从构思到上线的完整循环让我们通过一个具体的例子——为一个SaaS应用添加“团队邀请功能”——来演示bedrock工作流如何运行。4.1 阶段一澄清与定义人类工作更新0-vision/PLAN.md在项目计划中新增“团队协作模块”。创建3-workflow/BLUEPRINT.md这是功能说明书。内容需包括功能概述允许现有团队成员通过邮箱邀请新成员加入团队。用户故事作为团队管理员我希望邀请新成员以便他们能访问团队资源。技术规格后端创建team_invitations表字段id, team_id, email, token, inviter_id, status, expires_at。API端点POST /api/teams/:id/invitations(创建邀请)GET /api/invitations/:token(验证邀请)POST /api/invitations/:token/accept(接受邀请)。前端一个邀请表单一个邀请链接页面一个接受邀请的页面。设计参考附上Figma链接或描述UI组件使用1-design/COMPONENTS.md中的现有组件。安全与合规邀请令牌必须使用加密安全的随机数生成。邀请邮件必须包含取消订阅链接符合CAN-SPAM/GDPR。必须验证被邀请邮箱的域名是否在公司允许列表内参考SECURITY.md。验收标准列出5-7条具体的、可验证的完成标准。4.2 阶段二上下文注入与AI构建启动AI会话打开你的AI编码工具如Cursor。注入上下文Cursor会自动读取项目根目录的.cursorrules文件由bedrockCLI生成。这个文件本质上是2-context/目录下核心文件的精炼汇总确保了AI拥有全部必要的背景知识。开始构建你可以直接将BLUEPRINT.md中的“技术规格”部分复制给AI并附上指令“请根据BLUEPRINT.md和项目宪法实现团队邀请功能。请先给出数据库迁移文件然后是后端API最后是前端组件。每一步请先解释你的实现思路。”迭代与审查AI会生成代码。你的角色是审查架构一致性生成的API结构是否符合ARCHITECTURE.md中定义的模式安全性是否使用了参数化查询生成的邀请令牌是否足够随机RLS策略是否被正确考虑代码质量函数是否足够小且单一是否有明显的重复代码4.3 阶段三验证与闭环运行测试执行AI生成的测试并补充你可能想到的边缘情况测试。安全验证运行DEPENDENCIES.md中要求的审计命令。手动测试RLS尝试用匿名密钥查询team_invitations表应该返回空。更新3-workflow/HANDOFF.md本次会话结束前创建或更新交接文档。记录本次会话实现的功能。做出的关键决策及其原因例如选择使用JWT而非自定义令牌。遇到的任何问题及解决方案。下一步的建议。 这份文档消除了“上下文冷启动”问题。明天你或另一位开发者打开项目阅读HANDOFF.md就能立刻接上。提交代码遵循3-workflow/GIT.md中的提交规范例如feat: add team invitation API and UI。5. 安全实战超越检查清单的有效性验证bedrock的安全哲学是“验证有效性而非存在性”。让我分享几个从痛苦经历中总结的、超越普通检查清单的实战技巧。5.1 数据库行级安全实战陷阱许多教程告诉你“启用RLS”但很少告诉你如何验证它真的在工作。我曾在一个项目中AI生成了看似正确的RLS策略但因为在策略中错误地使用了USING (true)导致所有记录暴露。以下是我们的验证流程现在已写入项目的SECURITY.md创建验证脚本(scripts/verify_rls.sql)-- 假设使用Supabaseanon是匿名角色 \set ROLE anon \set TABLE_NAME your_sensitive_table SELECT :TABLE_NAME as table_name, EXISTS ( SELECT FROM pg_tables WHERE schemaname public AND tablename :TABLE_NAME ) as table_exists, EXISTS ( SELECT FROM pg_policies WHERE tablename :TABLE_NAME AND schemaname public ) as has_rls_policy, (SELECT COUNT(*) FROM public.:TABLE_NAME) as total_rows, (SELECT COUNT(*) FROM public.:TABLE_NAME) as rows_visible_to_anon WHERE current_setting(role) :ROLE;这个脚本会切换到匿名角色然后报告表是否存在、是否有RLS策略、总行数以及匿名用户能看到多少行。理想情况下rows_visible_to_anon应该为0。集成到CI/CD将上述脚本的运行作为CI流水线的一个步骤。任何合并请求如果导致匿名用户可见行数大于0则自动失败。5.2 依赖供应链防御“垃圾包投毒”与幻觉防御AI大约有20%的概率会“幻觉”出不存在的包名例如把lodash写成loadash。攻击者已经批量注册这些常见的拼错包名植入恶意代码等待AI或粗心的开发者上钩。我们的防御策略DEPENDENCIES.md中的强制审核流程任何新增依赖必须由人类在npmjs.com或PyPI上手动搜索确认。检查包的最新更新时间、维护者、下载量、开源仓库链接。一个上周刚创建、零下载量的包是危险信号。使用npm info package-name或pip show package-name查看详细元数据。使用锁定文件和可信仓库强制使用npm ci基于package-lock.json进行安装确保依赖树完全可复现。配置.npmrc将仓库源指向官方源或经过审计的内部镜像禁止从不受信任的源安装。AI提示词强化在AGENT.md中明确加入“在建议任何新的npm或pip包之前你必须声明’我建议添加包X。请注意这是一个外部依赖你需要手动在官方仓库验证其真实性和安全性后再安装。’”5.3 密钥与敏感信息管理最可怕的泄露往往不是黑客攻击而是意外提交。我们的规则立即忽略项目初始化后第一件事就是将.env.local,.env.production,*-config.yaml等文件加入.aiignore和.gitignore。使用环境变量模板创建.env.example文件列出所有需要的环境变量不含真实值并加入2-context/目录确保AI知道需要哪些配置但又接触不到真实值。CI/CD密钥隔离生产环境的部署密钥、数据库连接字符串只存储在GitHub Secrets或类似CI/CD平台中绝不进入代码库。6. 可持续性如何维护一个“氛围编码”诞生的项目这是bedrock最具前瞻性的部分。代码写出来只是开始维护才是真正的挑战。6.1 重新让AI“上车”MAINTAIN.md指南当你几个月后回到一个AI生成的项目如何让AI重新理解上下文MAINTAIN.md提供了“再入职”流程健康检查运行一套标准化的脚本检查依赖漏洞、过时的包、破碎的测试。上下文预热不要直接让AI修改代码。首先要求它“阅读项目的DECISIONS.md、ARCHITECTURE.md和最近5份HANDOFF.md文件然后写一份关于当前系统架构和状态的理解摘要。” 这能测试AI对项目的理解程度。渐进式任务从一个小而明确的修复或功能开始而不是一个大的重构。6.2 安全重构AI代码REFACTOR.md策略AI生成的代码有时会有奇怪的模式或重复。重构是必要的但必须谨慎。黄金法则一次只重构一个清晰定义的、有完整测试覆盖的模块。事前快照在开始重构前确保该模块的所有公开API都有完整的集成测试。如果没有先补测试。保持行为一致重构的目标是提升内部质量可读性、性能、结构而不是改变外部行为。使用差分测试或快照测试来确保。与AI结对将现有的代码和你的重构意图一起发给AI“这是当前的userService模块。我希望将其中的验证逻辑提取到一个独立的validation工具类中同时保持所有现有API的输入输出不变。请帮我规划重构步骤并优先为提取出的新函数编写测试。”6.3 人类交接手册HANDOFF_HUMAN.md如何向一个从未接触过此项目的人类开发者解释这个由AI辅助构建的代码库项目起源简要说明最初的问题、北极星指标。开发哲学解释这是一个“智能体工程”项目AI负责实现人类负责架构和审查。指出关键的上下文文件CONSTITUTION.md,ARCHITECTURE.md。代码库导航指出哪些部分是AI生成的可能风格统一但缺乏深层注释哪些部分是人工精心编写的核心逻辑。工作流说明如何启动开发服务器如何运行测试最重要的是如何与AI协作——即在修改任何东西前先阅读相关的DECISIONS.md和HANDOFF.md记录。“地雷”区域标注那些已知的、棘手但暂时没时间修复的代码区域。7. 工具链集成与自动化设置bedrock的init/setup.pyCLI是其易用性的关键。它通过一系列问题为你生成所有工具的配置文件。7.1 CLI设置流程详解运行python3 init/setup.py后你会被问到大约15个问题项目基本信息名称、简短描述。技术栈选择前端、后端、数据库、云服务商。这决定了STACK.md的内容和示例代码模板。设计风格从预置的几种UI风格如“现代简约”、“企业级”、“活泼创意”中选择或提供你自己的Tailwind配置/色彩体系。这会填充DESIGN.md和AESTHETIC.md。AI工具选择勾选你使用的所有工具可多选。CLI会为每个工具生成对应的配置文件。安全严格等级根据项目类型内部工具、MVP、生产SaaS选择安全级别这会影响SECURITY.md和DEPENDENCIES.md的严格程度。基于你的回答CLI会利用Jinja2模板引擎生成一个完整的、为你项目定制的bedrock目录结构所有文件都已预填充了相关上下文。7.2 生成的文件解析以.cursorrules为例对于Cursor用户会生成一个.cursorrules文件。它不是一个简单的提示词列表而是一个结构化的、引用了其他核心文件的文档。内容大致如下# Project Context Constitution ## Core Principles {{ include_from_file(‘2-context/AGENT.md’) }} ## Project Laws (DO NOT VIOLATE) {{ include_from_file(‘2-context/CONSTITUTION.md’) }} ## Tech Stack (Immutable) - **Frontend**: {{ stack.frontend }} - **Backend**: {{ stack.backend }} - **Database**: {{ stack.database }} - **Key Libraries**: {{ stack.libraries }} *Do not suggest alternatives without explicit user approval.* ## Current Focus We are currently implementing the feature described in: 3-workflow/BLUEPRINT.md Refer to 3-workflow/PLAN.md for the overall project roadmap. ## Code Style - Write small, pure functions. - Prefer async/await over callbacks. - Use the design tokens from 1-design/DESIGN.md for all UI work. - Follow the testing patterns in 5-quality/TESTING.md. ## Security Reminders - All SQL must be parameterized. - RLS must be enabled and tested for new tables. - Audit new dependencies before suggesting npm install.这种生成方式确保了“单一事实来源”。当你更新顶层的CONSTITUTION.md时所有工具的配置文件在下次运行CLI时都会同步更新保持了上下文的一致性。7.3 Web界面包的使用对于使用Claude.ai或ChatGPT Web版“项目”功能的用户bedrock会生成一个context-package/文件夹。这个文件夹包含了一个精简版的、按顺序加载的上下文文件集00-INDEX.md,01-AGENT.md, …。你只需要将这个文件夹整个上传到Web项目的上下文区域AI就能获得一个结构化的、全面的项目背景从而在聊天界面中也能进行高质量的、上下文感知的编码对话。这解决了Web版AI工具上下文碎片化的问题。8. 从理念到实践我的个人经验与避坑指南在过去几个月中我将bedrock方法论应用于两个中型项目和一个快速原型中。以下是一些最宝贵的经验教训经验一不要跳过“愿景”阶段即使它很痛苦。我曾为一个内部管理工具跳过0-vision/直接开始编码。三周后我们陷入了功能蔓延的泥潭因为每个利益相关者对工具的“核心”都有不同理解。被迫回头补做SPARK.md和SCOPE.md时我们才发现最初的目标如此模糊。花2小时争论并写下“非目标”节省了后面200小时的开发时间。经验二INTENT.md是应对“为什么这么蠢”的最佳防御。AI或新队友经常会质疑一些看似不优的设计。例如我们有一个“用户状态”字段用了复杂的枚举ACTIVE,PENDING,SUSPENDED,LEGACY而不是简单的布尔值。在INTENT.md中我们记录了“LEGACY状态用于迁移自旧系统的用户他们需要不同的登录流程。SUSPENDED与PENDING的区别在于前者是管理员手动暂停后者是等待邮箱验证。” 这避免了无数次的重复解释和潜在的“修复”尝试。经验三将安全验证自动化否则会被遗忘。最初我们的RLS验证是手动的。果然在一次紧急功能更新中我们忘了测。直到上线前一天才偶然发现一个数据泄露漏洞。现在我们按照bedrock的建议在4-security/.github/workflows/security.yml中集成了自动化的PostgreSQL测试。每次PR都会在一个临时数据库中创建表、应用RLS策略并以匿名角色运行查询测试。如果返回任何数据CI直接失败。这堵上了人为疏忽的漏洞。经验四HANDOFF.md是时间旅行机器。养成每次编码会话结束前花5分钟写HANDOFF.md的习惯。上周我需要修改一个两个月前由AI实现的、关于文件上传的复杂逻辑。如果没有当时的HANDOFF.md记录着“选择Pre-signed URL而非直接上传至服务器是为了避免后端负载并利用S3的冗余存储”我可能需要半天来重新理解这个决策。有了它我5分钟就进入了状态。最后的建议bedrock不是一个需要全盘接受的教条。从scales/MICRO.md开始。即使只采用AGENT.md、CONSTITUTION.md和PLAN.md这三个文件你也能立刻感受到项目清晰度和AI输出质量的显著提升。它的价值不在于复杂性而在于它强制你思考那些在“氛围编码”的热潮中最容易被忽略却又最为重要的基础问题。
