一套为Kiro及其他MCP兼容AI编程助手设计的项目模板，通过14个引导文件、自动化钩子和完整文档体系，强制实施TDD、规范驱动开发、安全审查等工程实践。

Kiro Rails：为AI编程助手注入工程纪律的完整框架\n\nAI编程助手如Kiro、Claude Code、Cursor等虽然功能强大，但它们本质上是"无状态"的——每次会话之间不会记住团队的工程标准。这导致了一个普遍问题：代理在不同会话中会漂移，跳过测试、硬编码密钥、创建临时文件结构、忽略变更日志，或在不同功能间产生不一致的代码。\n\nKiro Rails 正是为解决这一问题而生的项目模板。它通过一套精心设计的"引导文件"（Steering Files），将工程标准编码为持久化的上下文文档，让AI代理在每次交互时都能读取并遵循团队的规则。\n\n## 核心理念：从"写代码"到"按规范写代码"\n\n传统的AI编程工具关注的是"能不能生成代码"，而Kiro Rails关注的是"生成的代码是否符合团队标准"。这种思维转变类似于从"能说话"到"说得体的话"——不仅仅是功能实现，更是质量的保证。\n\n模板包含14个引导文件、4个自动化钩子、2个审查提示词、1个安全代理、1个TDD任务模板、3个文档模板和13个专用文档目录。这些组件共同构成了一套完整的工程纪律体系。\n\n## 引导文件体系：AI的行为准则\n\n引导文件是Kiro Rails的核心创新。它们不是简单的配置，而是详细的行为规范文档，告诉AI代理：\n\n代码组织方面：采用分层优先的后端架构和功能切片的前端架构，禁止随意创建文件夹。所有魔法数字必须集中到常量文件中，实现零硬编码。\n\n测试纪律方面：TDD是强制性的，必须遵循RED→GREEN→REFACTOR循环。代理不能只写实现不写测试，测试与实现必须同步完成。\n\n安全规范方面：预提交钩子会自动捕获代码中的密钥和敏感信息。安全审查流程涵盖OWASP对齐的审计类别，确保代码在提交前通过安全检查。\n\n文档标准方面：架构决策记录（ADR）必须在重大实现前完成，并关联到路线图里程碑。变更日志不是可选的，每次有意义的代码变更都必须更新。\n\n## 自动化钩子：质量门禁系统\n\nKiro Rails的钩子系统充当质量门禁，在每次文件编辑和提交时自动运行：\n\n- 预提交钩子：扫描代码中的密钥、密码、API令牌等敏感信息\n- 变更日志维护钩子：每次代码编辑后提醒代理更新CHANGELOG.md，超过500行时自动归档\n- 规范检查钩子：确保代码符合团队的代码风格和组织规范\n\n这些钩子不是建议性的，而是强制性的。它们确保质量检查成为工作流的自然组成部分，而不是事后的补救措施。\n\n## 文档分类体系：告别"文档抽屉"\n\n大多数团队都说"我们应该写文档"，但缺乏执行机制。Kiro Rails通过13个专用文档目录解决了这个问题：\n\n- docs/decisions/：架构决策记录（ADR），记录技术选择的理由和后果\n- docs/bugs/：编号化的缺陷文档，包含复现步骤、根因分析和修复描述\n- docs/specs/：规范文档，链接到路线图里程碑\n- docs/roadmap/：活的路线图文档，计划变更必须更新并记录理由\n- docs/changelog/：自动维护的变更日志，按功能整合而非每次提交一行\n\n每个目录都有明确的用途和放置规则，禁止在docs/根目录下放文件。想法从docs/ideas/毕业到规范，然后到归档。\n\n## 与工具链的兼容性\n\nKiro Rails设计为与任何MCP兼容的AI代理一起工作。虽然它是为Kiro优化的，但其原则适用于所有AI辅助开发工作流，包括：\n\n- Claude Code：Anthropic的官方CLI工具\n- Cursor：基于VS Code的AI编辑器\n- Windsurf：Codeium推出的AI IDE\n- Cline：开源的AI编程助手\n\n这种广泛的兼容性意味着团队可以在不同工具间保持一致的标准，不会因为更换工具而丢失工程纪律。\n\n## 安装与定制\n\n安装Kiro Rails非常简单，一条命令即可完成：\n\nbash\ncd your-project\ncurl -fsSL https://raw.githubusercontent.com/sourjya/kiro-rails/main/install.sh | bash\n\n\nWindows用户可以使用PowerShell版本：\n\npowershell\nirm https://raw.githubusercontent.com/sourjya/kiro-rails/main/install.ps1 -OutFile install.ps1; .\\install.ps1\n\n\n所有引导文件都是托管的，升级时会自动更新。但团队特定的设置可以放在.kiro/steering/user-project-overrides.md中，这个文件永远不会被覆盖。\n\n## 对比：有引导 vs 无引导\n\n| 维度 | 无引导文件 | 有Kiro Rails引导 |\n|------|-----------|-----------------|\n| 代码结构 | 临时文件夹结构 | 分层后端+功能切片前端 |\n| 魔法数字 | 随处可见 | 集中常量，零硬编码 |\n| 测试 | 偶尔写测试 | TDD强制，红绿重构循环 |\n| 安全 | 密钥可能泄露 | 预提交钩子自动捕获 |\n| UI规范 | 原生alert滥用 | 主题对话框，禁止原生弹窗 |\n| 文档 | 无决策记录 | ADR关联路线图里程碑 |\n| 流程 | 模糊规范 | 规范质量标准强制执行 |\n| 变更追踪 | 无变更日志 | 每次变更自动更新 |\n| 重构纪律 | 代理重构无关代码 | 仅触碰请求的范围 |\n\n## 实际意义与适用场景\n\nKiro Rails特别适合以下场景：\n\n初创团队：快速建立工程标准，避免技术债务累积\n远程团队：通过标准化减少沟通成本，确保分布式团队的一致性\nAI辅助开发：最大化AI编程助手的输出质量，减少人工审查负担\n代码审查优化：将基础规范检查自动化，让人工审查专注于架构和设计\n\n这套框架的价值在于将"好的工程实践"从依赖个人自觉转变为系统强制。它不会让AI代理变得更聪明，但会让它们的行为更可预测、更可审计、更符合团队标准。\n\n## 结语\n\nKiro Rails代表了一种新的AI编程范式：不再满足于"能生成代码"，而是追求"生成符合标准的代码"。在这个AI辅助开发日益普及的时代，工程纪律不是可选的奢侈品，而是质量的基石。Kiro Rails提供了一个经过深思熟虑的框架，帮助团队将这一理念落地为日常实践。

Kiro Rails：为AI编程助手注入工程纪律的完整框架\n\nAI编程助手如Kiro、Claude Code、Cursor等虽然功能强大，但它们本质上是"无状态"的——每次会话之间不会记住团队的工程标准。这导致了一个普遍问题：代理在不同会话中会漂移，跳过测试、硬编码密钥、创建临时文件结构、忽略变更日志，或在不同功能间产生不一致的代码。\n\nKiro Rails 正是为解决这一问题而生的项目模板。它通过一套精心设计的"引导文件"（Steering Files），将工程标准编码为持久化的上下文文档，让AI代理在每次交互时都能读取并遵循团队的规则。\n\n核心理念：从"写代码"到"按规范写代码"\n\n传统的AI编程工具关注的是"能不能生成代码"，而Kiro Rails关注的是"生成的代码是否符合团队标准"。这种思维转变类似于从"能说话"到"说得体的话"——不仅仅是功能实现，更是质量的保证。\n\n模板包含14个引导文件、4个自动化钩子、2个审查提示词、1个安全代理、1个TDD任务模板、3个文档模板和13个专用文档目录。这些组件共同构成了一套完整的工程纪律体系。\n\n引导文件体系：AI的行为准则\n\n引导文件是Kiro Rails的核心创新。它们不是简单的配置，而是详细的行为规范文档，告诉AI代理：\n\n代码组织方面：采用分层优先的后端架构和功能切片的前端架构，禁止随意创建文件夹。所有魔法数字必须集中到常量文件中，实现零硬编码。\n\n测试纪律方面：TDD是强制性的，必须遵循RED→GREEN→REFACTOR循环。代理不能只写实现不写测试，测试与实现必须同步完成。\n\n安全规范方面：预提交钩子会自动捕获代码中的密钥和敏感信息。安全审查流程涵盖OWASP对齐的审计类别，确保代码在提交前通过安全检查。\n\n文档标准方面：架构决策记录（ADR）必须在重大实现前完成，并关联到路线图里程碑。变更日志不是可选的，每次有意义的代码变更都必须更新。\n\n自动化钩子：质量门禁系统\n\nKiro Rails的钩子系统充当质量门禁，在每次文件编辑和提交时自动运行：\n\n- 预提交钩子：扫描代码中的密钥、密码、API令牌等敏感信息\n- 变更日志维护钩子：每次代码编辑后提醒代理更新CHANGELOG.md，超过500行时自动归档\n- 规范检查钩子：确保代码符合团队的代码风格和组织规范\n\n这些钩子不是建议性的，而是强制性的。它们确保质量检查成为工作流的自然组成部分，而不是事后的补救措施。\n\n文档分类体系：告别"文档抽屉"\n\n大多数团队都说"我们应该写文档"，但缺乏执行机制。Kiro Rails通过13个专用文档目录解决了这个问题：\n\n- docs/decisions/：架构决策记录（ADR），记录技术选择的理由和后果\n- docs/bugs/：编号化的缺陷文档，包含复现步骤、根因分析和修复描述\n- docs/specs/：规范文档，链接到路线图里程碑\n- docs/roadmap/：活的路线图文档，计划变更必须更新并记录理由\n- docs/changelog/：自动维护的变更日志，按功能整合而非每次提交一行\n\n每个目录都有明确的用途和放置规则，禁止在docs/根目录下放文件。想法从docs/ideas/毕业到规范，然后到归档。\n\n与工具链的兼容性\n\nKiro Rails设计为与任何MCP兼容的AI代理一起工作。虽然它是为Kiro优化的，但其原则适用于所有AI辅助开发工作流，包括：\n\n- Claude Code：Anthropic的官方CLI工具\n- Cursor：基于VS Code的AI编辑器\n- Windsurf：Codeium推出的AI IDE\n- Cline：开源的AI编程助手\n\n这种广泛的兼容性意味着团队可以在不同工具间保持一致的标准，不会因为更换工具而丢失工程纪律。\n\n安装与定制\n\n安装Kiro Rails非常简单，一条命令即可完成：\n\nbash\ncd your-project\ncurl -fsSL https://raw.githubusercontent.com/sourjya/kiro-rails/main/install.sh | bash\n\n\nWindows用户可以使用PowerShell版本：\n\npowershell\nirm https://raw.githubusercontent.com/sourjya/kiro-rails/main/install.ps1 -OutFile install.ps1; .\\install.ps1\n\n\n所有引导文件都是托管的，升级时会自动更新。但团队特定的设置可以放在.kiro/steering/user-project-overrides.md中，这个文件永远不会被覆盖。\n\n对比：有引导 vs 无引导\n\n| 维度 | 无引导文件 | 有Kiro Rails引导 |\n|------|-----------|-----------------|\n| 代码结构 | 临时文件夹结构 | 分层后端+功能切片前端 |\n| 魔法数字 | 随处可见 | 集中常量，零硬编码 |\n| 测试 | 偶尔写测试 | TDD强制，红绿重构循环 |\n| 安全 | 密钥可能泄露 | 预提交钩子自动捕获 |\n| UI规范 | 原生alert滥用 | 主题对话框，禁止原生弹窗 |\n| 文档 | 无决策记录 | ADR关联路线图里程碑 |\n| 流程 | 模糊规范 | 规范质量标准强制执行 |\n| 变更追踪 | 无变更日志 | 每次变更自动更新 |\n| 重构纪律 | 代理重构无关代码 | 仅触碰请求的范围 |\n\n实际意义与适用场景\n\nKiro Rails特别适合以下场景：\n\n初创团队：快速建立工程标准，避免技术债务累积\n远程团队：通过标准化减少沟通成本，确保分布式团队的一致性\nAI辅助开发：最大化AI编程助手的输出质量，减少人工审查负担\n代码审查优化：将基础规范检查自动化，让人工审查专注于架构和设计\n\n这套框架的价值在于将"好的工程实践"从依赖个人自觉转变为系统强制。它不会让AI代理变得更聪明，但会让它们的行为更可预测、更可审计、更符合团队标准。\n\n结语\n\nKiro Rails代表了一种新的AI编程范式：不再满足于"能生成代码"，而是追求"生成符合标准的代码"。在这个AI辅助开发日益普及的时代，工程纪律不是可选的奢侈品，而是质量的基石。Kiro Rails提供了一个经过深思熟虑的框架，帮助团队将这一理念落地为日常实践。