specx
为Python后端服务提供可执行的架构护栏和智能体技能。
安装使用
复制下面这段提示词发给你的 AI（Claude / Cursor / TRAE / Codex / WorkBuddy 等），它会自动帮你完成安装：
帮我安装这个 AI Skill：specx。 它的用途是：为Python后端服务提供可执行的架构护栏和智能体技能。 完整的 Skill 内容见：https://321skill.com/skills/specx/raw/index.md 请读取该页面内容，如果是 SKILL.md 格式直接安装，如果是 README 提炼核心 prompt 后安装。
提示词包含完整的 Skill 内容链接，AI 读取后即可完成安装。你也可以 查看完整内容 确认无误。
使用示例
“使用specx的技能，帮我创建一个用户管理微服务的项目骨架，并确保遵循分层架构。”，它会调用 specx 的初始化技能，生成一个包含用例层、服务层、仓储层等清晰目录结构的项目，并自动配置好相关的架构检查规则。或者，在开发过程中，你可以说：“检查当前代码是否违反了‘用例层必须返回DTO’这条架构规则。”，AI会运行 `specx check` 并给出具体的违规报告。
介绍
specx 旨在解决AI智能体在开发Python后端服务时，因缺乏统一架构约束而导致的代码混乱、层间耦合和维护困难等问题。它通过提供一套可执行的架构规则、类型化的基础类库和项目初始化工具，将架构设计转化为可自动检查的代码规范。
使用时，开发者或AI智能体可以通过CLI命令 specx init 快速创建一个符合规范的服务骨架，或通过 specx check 对现有项目进行架构合规性检查。其规则涵盖层间依赖、继承关系、事务边界、类型放置和测试一致性等多个维度，并支持在 pyproject.toml 中灵活配置。
该工具特别适合后端开发、全栈开发和智能体开发人员，尤其是那些在团队协作中需要维持代码架构一致性，或希望借助AI智能体高效生成结构化代码的开发者。
需要注意的是，specx 主要面向采用 src/ 布局的Python项目，并深度集成了 uv、Ruff、mypy 等现代Python工具链。对于小型脚本或非结构化项目，其约束可能显得过于严格。建议从新项目开始使用，或在现有项目中通过配置规则选择器逐步引入。
核心特点
与同类代码规范工具（如 linter）不同，specx 的核心在于提供一套完整的、可执行的“架构即代码”方案，它不仅检查代码风格，更通过预定义的业务架构层（如用例、服务、仓储）和明确的规则ID来强制执行架构模式，确保AI生成的代码符合预设的架构蓝图。
注意事项
主要面向中大型、结构化的Python后端服务项目，对于小型脚本或快速原型项目可能引入不必要的复杂性。
常见问题
specx 和普通的代码检查工具（如 pylint）有什么区别？
specx 专注于架构层面的约束（如禁止层间泄露、确保DTO返回），而非代码风格或语法错误，旨在维护服务级的架构完整性。
如何将 specx 集成到现有的项目中？
可以通过 `uv add specx` 添加依赖，然后运行 `uv run specx check` 进行检查，并通过 `pyproject.toml` 配置文件排除现有不合规的代码路径，逐步适配。
给 AI 助手的安装指引
如果你的 AI 编程助手（Claude Code、Cursor、TRAE 等）能看到这个页面，把下面这段发给它即可自动完成安装：
请访问 https://321skill.com/skills/specx/raw/index.md 读取 specx 的原始 Skill 定义（Markdown 格式），按其中说明在我的环境里完成安装和配置。
AI 可直接读取的原始 Markdown 地址：/skills/specx/raw/index.md（查看排版版本）