最近在 AI 开发工具的话题里tt-a1i 和 archify 被放在一起讨论的次数明显变多。前者被描述成一种更贴近开发流程的 AI 编排工具后者则常出现在代码仓库分析与架构治理的讨论中。如果只看表面很容易把这两类工具理解为“又一个代码生成器”或者“画架构图的辅助软件”但真正值得关注的变化其实是它们在尝试解决一个老问题为什么 AI 写出的代码能运行却往往不符合项目的架构这篇文章不打算替这两个工具写一份网上还找不到的官方说明书而是把关注点放在这一类“架构感知开发”工具的通用能力上。我会先解释为什么通用提示词在成熟项目里会失效再给出一套可以自行落地的架构约束方案包括架构文档、项目规则文件、Python 架构检查脚本和 CI 接入示例。读完这篇文章你应该能判断这类工具到底适配自己的项目也能动手搭出第一个架构守卫闭环。1. 从 tt-a1i / archify 看架构感知开发的定位先给一个明确判断tt-a1i 和 archify 这类工具真正想解决的不是“让 AI 多写几行代码”而是“让 AI 在正确的地方写代码”。如果项目只有一个临时脚本那架构感知带来的收益确实不大但如果项目已经有几十个模块、多个业务团队、复杂的依赖关系让 AI 自由生成代码的风险就会迅速放大文件放错了目录、跨层依赖被绕开、重复实现了一版已经存在的 Service这些问题比代码本身是否可运行更让人头疼。从目前可见的讨论来看这两类工具的关注点可以大致分成两条线关注点典型场景核心价值流程编排与 AI 工作流在需求、编码、审查、重构之间串联 AI 节点把 AI 生成能力嵌入已有开发流程架构分析与归档扫描代码库、提取模块边界、识别依赖方向把隐性的架构知识变成显性文档和规则这里的“归档”一词很关键。传统架构治理是自上而下的架构师画好图开发人员靠自觉遵守等到代码腐化后再靠 Code Review 和人工排查发现。而 archify 这类工具代表的思路是自下而上加闭环从代码里提取真实依赖和期望架构做对比把偏差暴露在审查或者 CI 阶段而不是等项目已经跑偏了再来补救。tt-a1i 代表的则是另一层能力不让 AI 每次从零理解项目而是把项目边界、编码约定和已有实现作为上下文让 AI 在回答问题时先“知道自己在哪个工程里”。这两条线合在一起就是当前 AI 辅助开发最值得投入的方向之一架构约束的工程化。2. 核心概念架构知识、上下文注入与架构约束要理解这类工具先要把三个概念区分开。第一个是架构知识Architecture Knowledge。它指的是一个项目在长期演进中形成的规则比如“api 层只做参数校验和路由转发”“业务逻辑必须写在 services 层”“数据访问只能通过 repositories 层完成”。这些规则通常不会出现在某个单一文档里而是散落在代码注释、设计评审记录、团队 Wiki 和老开发者的经验里。对新手来说这些知识是最难获得的部分而 AI 模型如果没有被显式告知也很难凭空推断出来。第二个是上下文注入Context Injection。模型在生成代码时只能依赖当前窗口里的信息如果上下文里没有架构规则它就只能基于通用代码风格输出结果。常见的上下文注入方式包括在系统提示词里补充项目说明、把架构文档作为文件挂载、通过检索增强生成RAG拉取相关代码片段或者像 AGENTS.md 这样把规则文件直接放在仓库根目录。这个环节决定了 AI 是“盲写”还是有依据地生成。第三个是架构约束Architecture Constraints。约束不只是“建议”而是可以被验证的规则。比如“services 层禁止导入 api 层”这样的规则如果只写在文档里它只是建议如果写成脚本在 CI 里跑它才变成约束。架构约束的价值在于它能把架构治理从“靠人记”变成“靠工具查”。用一句话概括三者的关系架构知识是人类经验上下文注入是把知识传递给 AI 的手段架构约束是把知识固化成自动化检查的产物。大多数架构感知工具的差异主要体现在后两点上——是只做了上下文注入还是真正把约束闭环起来了。3. 通用提示词为什么不够两个真实失败场景为了说明架构约束为什么必须工程化我准备了两个非常典型的失败场景。这两个场景在采用 AI 编码工具的中大型项目里几乎每天都会出现。3.1 场景一项目里已经有 ServiceAI 又写了一个假设项目里已经有一个UserService封装了用户注册、登录、资料更新的全部业务逻辑。开发者在 AI 工具里输入“帮我实现一个用户注册接口”。模型可能不知道项目里已经存在这个类或者知道但没有意识到应该优先复用于是直接生成一个新的UserRegisterUtil.py。代码当然能运行。但它带来了重复实现、接口不确定性、测试资源浪费等一系列问题。更麻烦的是没有人会主动承认这段代码是多余的它会在代码库里活很久直到某次重构时被人发现。这个场景说明通用提示词缺少项目级记忆。模型的训练数据再多也不知道你当前仓库里有什么类、什么函数、什么约定。如果不把“项目里已经存在什么”作为上下文注入进去AI 生成结果就必然有盲目性。3.2 场景二Controller 直接调了 Repository第二个场景更隐蔽。很多项目的架构文档都会写“Controller 不能直接访问数据访问层”但代码里可能已经存在一条从api/user_controller.py到repositories/user_repository.py的直接调用。这种调用在编译和运行时都不会报错架构检查也能通过因为大多数检查工具只关心语法不关心分层。如果 AI 在生成新接口时参考了这份“带病”代码它很可能会继续写出同样的跨层调用。日积月累services 层的存在意义就被架空了业务逻辑散落在 controller 里项目会越来越难维护。这两个场景的共同问题是架构规则没有被机器强制执行。文档写得再清晰人的注意力也会分散人的经验再丰富也没办法在每一行代码生成时都保持警惕。所以要真正解决这个问题必须让架构规则变成一种开发者、AI、CI 都能消费的产物。4. 让 AI 理解项目的架构先写 ARCHITECTURE.md 与 AGENTS.md在接入任何工具之前我建议先完成一项成本极低但收益最高的准备把项目的架构规则显性化。4.1 创建项目级架构文档ARCHITECTURE.md不应该是长篇大论的设计方案而应该是 AI 和开发者在生成代码前必须读到的“边界清单”。下面是一个最小可用的模板# 项目架构说明 ## 技术栈 - 语言Python 3.11 - Web 框架FastAPI - ORMSQLAlchemy 2.x - 数据库PostgreSQL ## 目录分层 - api路由入口负责参数校验和 HTTP 响应禁止写业务逻辑 - services业务逻辑层可以调用 repositories 和 models禁止被 api 层绕过 - repositories数据访问层只能处理持久化禁止导入 api 和 services - models数据模型层保持纯结构定义不依赖任何业务层 - common公共工具层可以被任何层依赖但禁止依赖业务层 ## 依赖方向 api - services - repositories - models common 可以被任何层引用但禁止反向依赖 ## 新增代码流程 1. 先查看当前目录是否已有可复用的 Service 2. 新增文件必须放到对应分层目录 3. 新接口先走 services 层再由 controller 调用 4. 如果依赖方向需要调整先同步修改本文件再更新检查脚本这份文档的价值在于它把藏在代码里的隐含规则变成了明确的输入。无论是人还是 AI拿到这个文件就能快速判断“某个文件应该放在哪里”“某个调用是否合理”。4.2 编写 AGENTS.md 项目规则文件现在很多 AI 编码工具会读取仓库根目录下的AGENTS.md或.cursorrules来了解项目上下文。这个文件不需要写得太长重点是把 AI 最容易犯的几条错误直接写清楚# AGENTS.md ## 项目背景 这是一个电商后端项目使用 FastAPI SQLAlchemy PostgreSQL。 请先阅读 ARCHITECTURE.md 了解分层再进行代码生成。 ## 架构约束 - 禁止在 api 层直接调用 repositories 层 - 禁止新建和已有 Service 重复的业务类 - 业务逻辑必须放在 services 层controller 只做参数解析 - 修改任务前先搜索项目中是否已有可复用实现 ## 完成标准 - 生成的代码必须符合目录分层规则 - 新增依赖方向时必须同时更新架构文档 - 输出代码前先检查一遍 import 是否有跨层依赖我见过不少团队觉得 AGENTS.md 就是给 AI 看的“背景介绍”随便写写就好。实际上它的作用更像是“提示词约束清单”。如果你没有把规则写进这个文件AI 在生成代码时就会默认使用通用编码风格而不是你项目的风格。4.3 把文档当代码管理架构文档和规则文件必须进入 Git 仓库并纳入 Code Review 范围。如果架构文档只是放在私有 Wiki 里它不会随着代码演进被更新一旦进入仓库每次架构调整都会留下变更记录这本身就是一种治理。不过到这里还只是完成了“上下文注入”真正让架构规则变得可靠还需要下一步把规则变成可执行检查。5. 把架构约束变成可执行检查一个 Python 架构检查器现在进入实操环节。我会带大家写一个不依赖任何第三方库的 Python 架构检查器。它的原理很简单扫描代码库里的所有.py文件解析 import 语句根据文件所在目录判断它属于哪一层再根据预定义规则判断这次依赖是否被允许。5.1 演示项目结构我们先建立一个演示用的后端项目demo-backend/ ├── api/ │ ├── __init__.py │ └── user_controller.py ├── services/ │ ├── __init__.py │ └── user_service.py ├── repositories/ │ ├── __init__.py │ └── user_repository.py ├── models/ │ ├── __init__.py │ └── user.py └── common/ ├── __init__.py └── logger.py期望的依赖规则是api可以依赖api、services、commonservices可以依赖services、repositories、models、commonrepositories可以依赖repositories、models、commonmodels只能依赖models、commoncommon只能依赖common5.2 架构检查脚本代码#!/usr/bin/env python3 arch_check.py —— 一个极简的 Python 架构依赖检查工具 用法: python arch_check.py demo-backend 原理: 1. 遍历根目录下所有 .py 文件 2. 使用 AST 解析 import 语句 3. 根据文件路径判断文件所属分层 4. 与预设规则比对输出违规结果 from __future__ import annotations import ast import sys from pathlib import Path # 分层关键词在路径中出现即认为属于该层 LAYERS { api: 1, services: 2, repositories: 3, models: 4, common: 0, } # 允许的依赖方向 ALLOWED { api: {api, services, common}, services: {services, repositories, models, common}, repositories: {repositories, models, common}, models: {models, common}, common: {common}, } def classify(file_rel: Path) - str: 根据文件路径在根目录下的相对位置判断所属层。 parts file_rel.parts for layer in LAYERS: if layer in parts: return layer return common def extract_imports(source: str) - list[str]: 解析源码中的绝对导入模块名。 tree ast.parse(source) imports [] for node in ast.walk(tree): if isinstance(node, ast.Import): imports.extend(alias.name for alias in node.names) elif isinstance(node, ast.ImportFrom) and node.module: imports.append(node.module) return imports def get_target_layer(import_name: str) - str | None: 根据导入模块名判断目标层。 for layer in LAYERS: if import_name layer or import_name.startswith(layer .): return layer return None def check_file(file_path: Path, root: Path) - list[str]: 检查单个文件是否存在跨层依赖。 relative file_path.relative_to(root) current_layer classify(relative) if current_layer not in ALLOWED: return [] violations [] try: source file_path.read_text(encodingutf-8) imports extract_imports(source) except (SyntaxError, UnicodeDecodeError) as e: return [f[跳过] {relative}: 源码解析失败: {e}] for import_name in imports: target_layer get_target_layer(import_name) if target_layer is None: continue if target_layer not in ALLOWED[current_layer]: violations.append( f{relative}: 禁止依赖 {import_name} (目标层: {target_layer}) ) return violations def main() - int: if len(sys.argv) 2: print(用法: python arch_check.py 代码根目录) return 2 root Path(sys.argv[1]).resolve() violations: list[str] [] for py_file in root.rglob(*.py): # 跳过虚拟环境目录 if .venv in py_file.parts or venv in py_file.parts: continue violations.extend(check_file(py_file, root)) if not violations: print(架构检查通过) return 0 print(\n.join(violations)) print(f\n共发现 {len(violations)} 个架构违规) return 1 if __name__ __main__: sys.exit(main())这段代码有几个关键点需要说明。classify函数采用“路径中包含分层关键词”的策略所以api/user_controller.py会被归类为api层repositories/user_repository.py会被归类为repositories层。这个策略虽然简单但对大多数遵循目录分层的项目已经足够。extract_imports只处理语法层面的绝对导入。为什么这么做因为 AST 解析速度快、不依赖实际运行环境也不需要安装项目依赖特别适合作为 CI 里的第一道快速检查。它抓不到动态导入和反射调用但能解决 80% 的跨层依赖问题。规则定义用了“允许集合”而不是“禁止集合”。这是个刻意的设计默认拒绝所有未列出的依赖方向比默认放行更安全。将来如果项目需要增加新的依赖方向就等于要显式地修改规则而不是悄悄绕过检查。5.3 故意制造一个违规示例为了验证检查器能工作我们在第一个版本里写一个违规文件# 文件路径demo-backend/api/user_controller.py from repositories.user_repository import UserRepository def get_user(user_id: int) - dict: # 这里绕过了 services 层直接访问数据访问层属于架构违规 repo UserRepository() user repo.find_by_id(user_id) return {id: user.id, name: user.name}运行检查python arch_check.py demo-backend预期输出demo-backend/api/user_controller.py: 禁止依赖 repositories.user_repository (目标层: repositories) 共发现 1 个架构违规修复方式是让 controller 调用 service# 文件路径demo-backend/api/user_controller.py from services.user_service import UserService def get_user(user_id: int) - dict: service UserService() return service.get_user(user_id)再次运行检查输出架构检查通过到这里我们已经把一条架构规则变成了可以自动验证的产物。6. 把架构检查接入 CI 与 AI 工作流脚本能跑通还不够更关键的是让它在正确的时机自动运行。6.1 接入 GitHub Actions在仓库里新增 workflow 文件# 文件路径.github/workflows/arch-check.yml name: arch-check on: pull_request: paths: - backend/** - arch_check.py - .github/workflows/arch-check.yml jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.11 - name: Run architecture check run: python arch_check.py backend把检查放在 Pull Request 阶段而不是代码合并后是为了尽早暴露问题。这样架构违规会直接阻断合并而不是等合并后才在主干上被发现。6.2 与 AI 编码工具形成反馈闭环架构检查不只是 CI 的守门员它还可以反向喂给 AI 工具。具体做法是把检查结果放进提示词上下文让 AI 在下一轮生成时主动修复。一个可用的提示词模板你是这个项目的高级后端工程师。下面是架构检查工具的输出 {arch_check_output} 请根据架构约束修复代码 1. 先定位跨层依赖的具体位置 2. 找到当前目录下可复用的 services 层实现 3. 修改 controller 调用方式 4. 说明你修改了哪些文件以及为什么这样改 项目架构约束请参考 AGENTS.md 和 ARCHITECTURE.md。这里的关键不是让 AI 直接重写整个文件而是让它先读检查结果再对照架构文档做最小修改。重复几轮之后模型对项目的架构理解会越来越准确生成代码的命中率也会明显提升。6.3 不要让检查脚本成为唯一的判断来源架构检查能捕获语法层面的依赖方向问题但它无法判断“这个业务逻辑放在 services 里到底对不对”。所以更合理的定位是把脚本当作快速反馈的第一道关把真正的人类 Code Review 留给需要业务判断的部分。工具负责守住基线人负责守住质量。7. 运行结果与效果验证为了验证整套流程是否有效建议做以下三步验证。7.1 验证正常路径准备一个干净的分层项目确保所有 import 都符合规则运行python arch_check.py demo-backend预期输出应该是架构检查通过如果脚本正确退出码是 0CI 步骤显示绿色。7.2 验证违规路径在api层中新增一条从repositories导入的代码例如from repositories.user_repository import UserRepository然后重新运行脚本python arch_check.py demo-backend预期输出demo-backend/api/user_controller.py: 禁止依赖 repositories.user_repository (目标层: repositories) 共发现 1 个架构违规退出码是 1CI 步骤显示红色。这说明规则确实在起作用。7.3 验证 CI 接入效果提出一个 Pull Request故意包含上述违规代码。此时 GitHub Actions 应该触发arch-check工作流并在检查步骤失败。这样可以确认两件事脚本本身能发现问题workflow 的触发路径配置正确。如果 CI 没有按预期运行优先检查on.pull_request.paths是否包含了你修改文件的路径。比如违规文件在其他目录里但paths只监听了backend/**那工作流就不会触发。8. 常见问题与排查方法问题现象可能原因排查方式解决方案脚本报错demo-backend/api/user_controller.py: 禁止依赖 repositories.user_repository代码确实存在跨层依赖或者分层规则定义过严查看文件路径和 import 语句确认是否真的需要该依赖如果是真违规调整代码如果是误报修改规则或增加白名单相对导入没有被检查到from .services import UserService等相对导入在 AST 里可能被解析为目标模块名services打印extract_imports的输出确认当前层和目标层后决定是否需要解析相对导入原型阶段可先跳过CI 里跑不出结果workflow 的paths没有覆盖改动文件或者 python 版本不一致查看 Actions 日志确认 workflow 是否被触发调整paths固定 Python 版本大量文件被误判为commonclassify只按路径关键词判断路径中没有分层关键词时默认是common打印每个文件的分类结果增加分层关键词或按目录前缀做更精确的判断项目使用了动态导入检查器无法发现AST 只能看到静态 import看不到importlib.import_module()结合人工 Code Review加入依赖图工具在架构检查之外增加代码扫描用例架构文档更新了但检查脚本没有同步文档是人工维护脚本是另一份规则容易漂移将规则集中在单一配置文件避免重复维护把分层规则抽到rules.json脚本和文档都从同一份配置生成这里最值得强调的一点是架构检查脚本要和架构文档使用同一份规则来源否则就会出现“文档说一套脚本查另一套”的局面。最简单的做法是把分层关键词和依赖方向都放到一个配置文件里。{ layers: [api, services, repositories, models, common], allowed: { api: [api, services, common], services: [services, repositories, models, common], repositories: [repositories, models, common], models: [models, common], common: [common] } }脚本读取这份配置后动态生成规则文档也由同一份配置自动渲染。这样即使规则调整也不会出现文档和检查不一致的问题。9. 最佳实践与工程建议9.1 先从最少规则开始不要一开始就把所有架构规则写成脚本。规则的维护成本是真实存在的规则过严会挡住正常开发规则过松则没有效果。建议先选择两到三条最容易出错的规则比如“Controller 禁止直接访问 Repository”“业务逻辑禁止写在路由层”“新增文件必须放入正确目录”跑通闭环后再逐步扩充。9.2 把规则沉淀成修复示例架构检查器只能告诉开发者“哪里违规”很难直接告诉你“应该怎么改”。如果团队里大量使用 AI 编码工具建议把每个违规类型的修复示例沉淀进知识库并让 AI 工具在生成代码前引用这些示例。比如修复示例 违规代码 from repositories.user_repository import UserRepository 修复方式 from services.user_service import UserService这样一来下一次 AI 生成类似代码时就不再只是被“拒绝”而是被“引导”。9.3 区分“硬规则”和“软建议”不是所有规则都适合用脚本强制。依赖方向这种确定性问题适合硬校验而“命名风格是否清晰”“函数是否过长”这类主观问题更适合用提示词和 Code Review 来解决。把软建议硬编码成脚本只会让团队对工具产生疲劳感。9.4 注意数据安全与代码库权限接入 AI 编码工具时要关注代码内容会被发送到哪个服务端。对于敏感项目建议使用企业内部部署或私有化版本并设定最小权限。不要随意将内部代码、密钥或未公开的业务逻辑作为上下文发送到外部 AI 服务。这一点在评估 tt-a1i 和 archify 这类工具时尤其重要先确认数据链路再讨论功能。9.5 工具是反馈环不是银弹架构治理的终极目标不是“所有代码都符合规则”而是“规则能跟上项目演进”。工具能让违规更快暴露但它不能替代架构师对业务边界的判断。实际项目中真正有效的做法是模板约束新项目、脚本检查存量项目、人工评审关键变更三者一起运转。10. 总结与后续学习方向回到文章开头的问题为什么 tt-a1i 和 archify 这类工具值得关注因为它们代表了一种新的开发范式——架构知识不再是藏在人脑里的隐形成本而正在变成可以被文档记录、被工具检查、被 AI 消费的工程产物。本文从概念、失败场景、文档规范、检查脚本、CI 接入到最佳实践完整演示了一套轻量级的架构守卫方案。文中提供的arch_check.py不是生产级工具但它足以让你理解原理再根据自己项目的语言和结构去扩展。下一步你可以做这几件事在真实项目里先写出ARCHITECTURE.md和AGENTS.md让团队按同一套规则协作把本文的检查脚本改造成适合自己技术栈的版本接入 CI再抽样观察几个迭代周期看看架构违规减少到什么程度以此决定是否值得引入更复杂的架构分析工具。AI 写代码的成本会越来越低但架构治理的成本不会自动降下来。谁能先让 AI 理解项目的边界谁就能在 AI 驱动的开发流程里少交学费。