工匠编码者：SOLID、AST CodeGraph 影响与证据优先工程
一个纪律严明、与仓库无关的工程工作流，用于构建健壮、解耦且可验证的软件。
核心原则
- AST 与 CodeGraph 探索优先： 切勿盲目修改或重构代码。在更改实现之前，务必映射符号定义、调用者、被调用者以及爆炸半径。
- SOLID 与单一职责原则：
每个模块、函数和类必须只有一个变更原因。将业务逻辑与 I/O、持久化和外部 API 分离。
- 分解规则： 如果一个组件、类或函数过长或处理多个关注点，立即将其分解为具有单一职责的、更小的原子性子组件/服务。
- 依赖注入与控制反转： 通过构造函数或框架机制注入依赖项（仓库、客户端、日志记录器）。将逻辑与具体基础设施解耦。避免硬编码的直接外部实例化。
- 后备架构：垂直切片架构 + EIP：
如果仓库没有既定的框架约定，始终优先使用垂直切片架构结合 SOLID 和企业集成模式：
- 按业务能力组织代码（
features/<feature_name>/），使用请求-端点-响应模式，而非水平技术层。 - 使用 EIP 模式进行切片协调：命令/查询路由器、管道和过滤器、幂等接收器以及领域事件发布/订阅。
- 详细指南：Vertical Slice & EIP 指南
- 按业务能力组织代码（
- 确定性 VSA 架构边界检查：
当仓库实现 VSA 时，配置一个确定性边界检查器（例如，JS/TS 的
dependency-cruiser、Python 的import-linter、Go 的depguard或vsa_boundary_checker.py）以禁止直接的跨切片导入。 - 强制性的仓库级
GEMINI.md： 在创建或初始化任何仓库时，始终在仓库根目录生成一个项目级别的GEMINI.md，以持久化架构选择、边界规则和 Gauntlet 命令。- 严格可移植性规则： 由于此文件会提交和推送，切勿引用外部主机路径（例如，无
~/.gemini/config/...，无/data/data/...）或机器特定的密钥。它必须是 100% 自包含且可移植的。
- 严格可移植性规则： 由于此文件会提交和推送，切勿引用外部主机路径（例如，无
- 实时网络研究与最优 Big-O 复杂度：
始终选择具有最优 Big-O 时间和空间复杂度的算法和数据结构模式（$O(1)$ 查找、$O(N \log N)$ 排序、流式 $O(1)$ 内存）。
- 强制性网络研究： 切勿仅依赖预训练假设，因为知识可能已过时。务必根据当前年月进行网络搜索，以发现最先进的算法模式、最优数据结构和最新的高性能库实现。
- 高性能、低内存库与企业许可合规：
- 峰值性能与低内存： 优先选择现代、缓存友好、零拷贝、SIMD 加速的库（例如
orjson/msgspec、polars、sonic、zerolog、simd-json、fast-json-stringify）。 - 企业许可合规： 选择宽松的开源许可证（MIT、Apache 2.0、BSD-2/3、ISC）。严格避免病毒式 copyleft 许可证（
GPL、AGPL、SSPL），以确保顺利通过企业审计，避免源代码披露责任。 - 详细指南：高性能库与许可指南
- 峰值性能与低内存： 优先选择现代、缓存友好、零拷贝、SIMD 加速的库（例如
- 针对 SRP 与抽象的确定性静态代码分析： 始终优先使用确定性静态分析工具来审计代码是否违反 SRP（例如，过长的长度、过多的职责）以及是否绕过抽象（例如，在表示/业务逻辑中直接进行原始 SQL 或 HTTP 调用）。
- 集中式密钥注入：
切勿将密钥硬编码或将原始凭据存储在 git/本地环境文件中。将密钥视为通过 Infisical 运行时注入的依赖项（
infisical run -- ...）。- 详细指南：Infisical 密钥管理指南
- 框架约定优先：
尊重现有框架的习惯约定（例如，FastAPI
Depends、NestJS@Injectable、React hooks、Go 接口），而非发明临时的抽象。 - 可并行化的封闭测试：
所有测试必须是无状态、隔离且可并行化的（例如，
pytest -n auto、go test -parallel）。不允许共享可变状态或静态单例副作用。 - “Old Coder”证据优先纪律： 审查证据，而非代码。遵循规范 -> RED -> GREEN -> REFACTOR 循环，并在报告完成前通过自动化终端检查进行验证。
- AI 代理就绪的工具与技能工程：
在将重复模式提取到工具和技能中时：保证
--json输出、非交互式执行（零提示）、--dry-run安全性、可预测的名词-动作动词以及类型化的退出码。- 详细指南：AI 代理就绪的 CLI 设计指南
分步工作流
步骤 1：变更前爆炸半径分析
在修改函数、类或服务之前，检查爆炸半径以确定下游影响：
python3 ~/.gemini/config/skills/craftsman-coder/scripts/codegraph_impact.py <path_to_repo> --symbol <TargetSymbol>
- 审查直接调用者和引用文件。
- 审查受影响的测试套件：如果没有测试覆盖此符号，则必须在重构之前创建一个。
步骤 2：架构、算法 Big-O 与仓库级 GEMINI.md
- 制定清晰的规范和设计：
- 如果创建/初始化仓库，则在仓库根目录创建自包含的
GEMINI.md（零外部路径，零密钥）。 - 如果不存在框架约定，则按垂直切片（
features/<name>/）组织，使用 REPR 和 EIP 模式。 - 设置或验证架构边界检查器（例如，
dependency-cruiser、import-linter或vsa_boundary_checker.py）。 - 类/函数/组件是否在做一个以上的事情或超过长度阈值？将其分解为聚焦的子组件（SRP）。
- 外部系统是否紧密耦合？定义一个接口/协议并使用依赖注入。
- 算法复杂度与网络搜索： 基准测试 Big-O 时间/空间复杂度。根据当前年月主动搜索网络，以寻找现代算法优化。
- 依赖审计： 选择低内存、高吞吐量且具有企业安全许可证（MIT / Apache 2.0 / BSD）的库。确保零 copyleft/AGPL 传递依赖。
- 如果创建/初始化仓库，则在仓库根目录创建自包含的
- 详细参考：SOLID & DI 模式指南
- 详细参考：Vertical Slice & EIP 指南
- 详细参考：VSA 边界强制执行与仓库 GEMINI.md 指南
- 详细参考：高性能库与许可指南
步骤 3：编写可并行化的测试
- 编写一个隔离、封闭的单元或集成测试，验证预期的行为或错误修复。
- 确保测试使用独立的临时资源或内存模拟。
- 运行测试以确认其失败（RED）。
- 详细参考：并行测试与 Old Coder 指南
步骤 4：实现最小、清晰的解决方案
- 仅实现满足测试所需的内容。
- 保持组件内聚且单一用途。
- 清晰注入依赖项。
步骤 5：重构与 Gauntlet
- 在测试保持通过的情况下清理代码。
- 运行 Gauntlet（所有验证必须自动且确定）：
- VSA 边界检查：
运行架构边界检查（例如，
npx depcruise --config .dependency-cruiser.js src或python3 ~/.gemini/config/skills/craftsman-coder/scripts/vsa_boundary_checker.py <path_to_repo>）。 - 确定性静态 SRP 与抽象分析：
python3 ~/.gemini/config/skills/craftsman-coder/scripts/static_srp_analyzer.py <path_to_repo> --strict - 代码检查器与静态分析（例如
ruff check .、eslint、golangci-lint） - 类型检查（例如
mypy、tsc --noEmit） - 完整测试套件，并行执行（例如
pytest -n auto、go test -parallel 4 ./...）
- VSA 边界检查：
运行架构边界检查（例如，
- 在最终响应中提供终端证据（退出码、测试通过摘要）。
内置脚本与工具
-
CodeGraph AST 影响分析器：
scripts/codegraph_impact.py- 检查 AST 并交叉引用 Python、JS/TS、Go、Rust、Java。
- 计算爆炸半径风险级别（低、中、高、严重）。
- 识别直接调用者和受影响的测试套件。
-
确定性静态 SRP 与抽象分析器：
scripts/static_srp_analyzer.py- 评估代码的长度/复杂度违规以判断 SRP。
- 标记抽象绕过（在仓库/适配器之外的原始 SQL/HTTP 调用）。
- 输出机器可读的
--json和确定性退出码，用于 CI/Old Coder 验证。
-
VSA 架构边界检查器：
scripts/vsa_boundary_checker.py- 通过禁止非法跨切片导入来强制切片隔离。
- 可通过
.vsa-boundaries.json配置。零依赖，与仓库无关（MIT 许可）。