要实现"将架构约束写成自定义 Lint 规则，并将错误信息转化为 AI 的修复指南（Prompt）"，你需要完成三个核心步骤：编写静态分析脚本 、设计面向 AI 的报错信息 、将其接入 CI/CD 流水线。
以下是具体的落地实现方案：
第一步：编写基于 AST 的自定义 Linter
Python 内置的 ast（抽象语法树）模块是进行静态代码分析的最佳工具。它可以在不执行代码的情况下，精准扫描 import 语句并检查架构违规。
以下是一个检查"领域层（domain）禁止依赖基础设施层（infrastructure）"的自定义 Linter 示例：
python
# scripts/lint_architecture.py
import ast
import sys
from pathlib import Path
# 定义架构约束规则
FORBIDDEN_IMPORTS = {
"src/domain": ["src.infrastructure", "src.interfaces"],
}
def check_architecture(filepath: Path) -> list[str]:
errors = []
# 检查当前文件是否命中了约束规则
for restricted_dir, forbidden_modules in FORBIDDEN_IMPORTS.items():
if str(filepath).startswith(restricted_dir):
with open(filepath, encoding="utf-8") as f:
tree = ast.parse(f.read())
for node in ast.walk(tree):
if isinstance(node, ast.ImportFrom) and node.module:
for forbidden in forbidden_modules:
if node.module.startswith(forbidden):
# 核心：构造面向 AI 的错误信息
errors.append(
f"❌ [架构违规] {filepath} 第 {node.lineno} 行: "
f"领域层禁止直接导入基础设施层模块 '{node.module}'。\n"
f"💡 [修复建议] 请遵循依赖倒置原则。在 domain 层定义抽象接口（如 Repository），"
f"在 infrastructure 层实现该接口，并通过依赖注入传入。\n"
f"📚 [参考文档] 请查阅 docs/architecture.md#dependency-rules 了解详细规范。"
)
return errors
if __name__ == "__main__":
all_errors = []
for pyfile in Path("src").rglob("*.py"):
all_errors.extend(check_architecture(pyfile))
if all_errors:
print("\n".join(all_errors))
sys.exit(1) # 返回非零退出码，阻断流水线
print("✅ 架构规则检查通过")第二步：掌握"错误信息即 Prompt"的设计原则
传统的 Linter 报错是给人看的（例如 ImportError 或 Architecture violation），但 AI 需要的是结构化的上下文。在设计报错信息时，必须包含以下三要素：
- 为什么不能这么做（Rationale）：解释规则背后的架构意图，帮助 AI 理解上下文。
- 应该用什么替代（Actionable Fix）：提供具体的重构方向或代码模式（如"使用依赖注入"）。
- 去哪里看正确的例子 （Reference）：指向项目中的深度文档（如
docs/目录下的 Markdown 文件），让 AI 能够按需检索。
这种设计将 Linter 的报错变成了一个"现场教学时刻（Teaching Moment）"，AI 在读取到报错后，可以直接将其作为下一轮 Prompt 的输入，自行完成修复闭环。
第三步：接入 CI/CD 与 Harness 流水线
将编写好的 Linter 脚本集成到自动化流程中，使其成为 AI 无法绕过的"机械护栏"：
- 配置 CI 门禁：在 GitHub Actions 或 GitLab CI 中添加执行该脚本的步骤。只要 AI 生成的代码触发了违规，CI 就会失败并返回上述详细的错误日志。
- 结合 LLM 驱动的代理审查：在 AI 提交 PR 之前，先运行此 Linter。如果失败，AI 会自动读取错误信息并修改代码，直到 Linter 通过后才允许进入人工或语义层面的审查。
- 使用专业工具替代手写（进阶） ：如果项目规模较大，手写 AST 维护成本较高，可以引入
import-linter等开源工具。通过在.importlinter配置文件中定义"契约（Contracts）"，工具会自动扫描依赖图，你只需专注于配置契约和优化报错输出即可。
💡 最佳实践建议
- 渐进式引入：不要一开始就开启所有规则。可以先将违规项记录为 Warning，让 AI 和团队适应一段时间，再转为强制阻断（Error）。
- A/B 测试 Harness 规则：每增加一条 Linter 规则，对比 AI 任务的成功率。如果某条规则没有明显改善 AI 的产出质量，或者导致 AI 陷入无限修复循环，应果断移除，防止 Harness 膨胀。
- 定期清理：随着项目演进，某些架构约束可能不再适用。可以部署专门的"垃圾回收 Agent"定期扫描过时的 Linter 规则并发起重构 PR。