Codex CLI教程（特殊篇） | CC-SDD-说明与使用指南

Codex CLI教程（特殊篇） | CC-SDD-说明与使用指南

• [1. 一页看懂](#1. 一页看懂)
• [2. 它解决什么问题](#2. 它解决什么问题)
• [3. 适用判断](#3. 适用判断)
• [4. 安装与生成结果](#4. 安装与生成结果)
• • 安装命令
  • 关键规则
  • 安装后会新增
• [5. 生成的文件分别干什么](#5. 生成的文件分别干什么)
• [6. 读命令前先记住两条规则](#6. 读命令前先记住两条规则)
• • [规则 1：每个阶段通常要你手动启动](#规则 1：每个阶段通常要你手动启动)
  • [规则 2：大部分命令后面都要带 spec 名称](#规则 2：大部分命令后面都要带 spec 名称)
  • 这个名字是谁给的
• [7. 最常用主流程](#7. 最常用主流程)
• [8. 命令总览与速查](#8. 命令总览与速查)
• • 分类总览
  • [核心 6 个](#核心 6 个)
  • 速查表
• [9. 安装后最常改的地方](#9. 安装后最常改的地方)
• [10. 官方地址](#10. 官方地址)
• [11. 安全结论](#11. 安全结论)

1. 一页看懂

项目	结论
它是什么	面向 AI 编码代理的规格驱动开发工作流
核心流程	需求 -> 设计 -> 任务 -> 实现
是否全自动	不是
正确理解	你启动阶段，它在阶段内主动展开
适合谁	想把 AI 开发做得更规范、更可控的个人开发者或小团队
安装方式	在项目根目录执行 npx cc-sdd@latest --codex-skills

---

2. 它解决什么问题

• 需求没定清楚就开始写代码
• 设计和实现脱节
• 功能边界不清
• 任务拆分混乱
• 项目后期难维护

一句话：它把 AI 开发从"直接出代码"改成"按流程推进"。

---

3. 适用判断

适合	不太适合
新项目从 0 到 1	只想临时补几段代码
现有项目增加较大功能	不愿意维护文档和流程
需要沉淀需求、设计、任务文档	只做零碎小改动
希望 AI 更可控	追求一句话全自动到底

---

4. 安装与生成结果

安装命令

先进入项目根目录：

cd D:\Develop\Personal\trae-codex-test-v7

再执行：

npx cc-sdd@latest --codex-skills

关键规则

cc-sdd 是项目级安装。你在哪个目录执行，它就把文件生成到哪个目录。

安装后会新增

AGENTS.md
.agents/
.codex/
.kiro/

---

5. 生成的文件分别干什么

路径	作用
AGENTS.md	项目总规则，定义工作流、目录、协作方式
.agents/skills/	项目级 skills，也就是 kiro-* 命令背后的规则
.codex/agents/	agent 配置，如模型、推理强度、角色说明
.kiro/settings/templates/	文档模板，决定 specs 和 steering 怎么生成

---

6. 读命令前先记住两条规则

规则 1：每个阶段通常要你手动启动

不是每个细节都要手动，但每个阶段通常要你手动启动。

最准确的说法是：

阶段切换靠你启动，阶段内部由它主动执行。

例如你执行：

$kiro-spec-design blog-system

它通常会自己读取前置文档、套用模板、组织内容，必要时还会做 review 或 validation。

所以它不是全自动流水线，而是分阶段工作流。

规则 2：大部分命令后面都要带 spec 名称

例如：

$kiro-spec-init blog-system
$kiro-spec-requirements blog-system
$kiro-spec-design blog-system
$kiro-spec-tasks blog-system
$kiro-impl blog-system

这里的 blog-system 不是多余参数，而是 spec 名称。

你可以把它理解成：

• 这套规格的名字
• 这条需求链路的唯一标识
• .kiro/specs/ 下面的目录名

例如：

.kiro/specs/blog-system/

后续命令就是靠这个名字去定位同一套文件，例如：

• .kiro/specs/blog-system/spec.json
• .kiro/specs/blog-system/requirements.md
• .kiro/specs/blog-system/design.md
• .kiro/specs/blog-system/tasks.md

这个名字是谁给的

常见有两种来源：

• 你自己定，例如 blog-system
• discovery / spec-init 根据你的描述帮你生成一个规范名称

这个名字通常不能省。

因为从 requirements、design、tasks、impl 开始，命令都需要知道自己正在操作哪一个 spec。

如果一个项目里同时有：

.kiro/specs/blog-system/
.kiro/specs/admin-dashboard/
.kiro/specs/comment-module/

那你只写：

$kiro-spec-design

它就不知道该处理哪一个目录。

最简单的记法是：

把它直接理解成你当前这套 spec 的文件夹名。

---

7. 最常用主流程

第一次使用，建议按标准顺序来：

$kiro-discovery 个人开发者博客系统，前端 Vue 3 + TypeScript，后端 Spring Boot 3 + MyBatis-Plus + MySQL，支持文章、项目展示、后台管理和 SEO
$kiro-spec-init blog-system
$kiro-spec-requirements blog-system
$kiro-spec-design blog-system
$kiro-spec-tasks blog-system
$kiro-impl blog-system

可选前置命令：

$kiro-steering
$kiro-steering-custom

---

8. 命令总览与速查

你当前项目里实际安装出来的 kiro-* 命令一共是 17 个。

分类总览

分类	数量	命令
项目共识	2	kiro-steering、kiro-steering-custom
发现与初始化	3	kiro-discovery、kiro-spec-init、kiro-spec-status
规格生成	4	kiro-spec-requirements、kiro-spec-design、kiro-spec-tasks、kiro-spec-quick
批量规格	1	kiro-spec-batch
验证与检查	4	kiro-validate-gap、kiro-validate-design、kiro-validate-impl、kiro-verify-completion
实现与辅助	3	kiro-impl、kiro-review、kiro-debug

核心 6 个

日常主线最常用的其实只有这 6 个：

• kiro-discovery
• kiro-spec-init
• kiro-spec-requirements
• kiro-spec-design
• kiro-spec-tasks
• kiro-impl

速查表

命令	是否通常手动启动	主要作用
kiro-steering	是	生成项目级共识
kiro-steering-custom	是	生成自定义工程规范
kiro-discovery	是	梳理需求边界，判断后续路径
kiro-spec-init	是	初始化 spec
kiro-spec-requirements	是	生成需求文档
kiro-spec-design	是	生成设计文档
kiro-spec-tasks	是	生成任务拆分
kiro-spec-quick	是	快速走完单 spec 流程
kiro-spec-batch	是	批量生成多 spec
kiro-spec-status	是	查看 spec 当前状态
kiro-validate-gap	是	检查 spec 与现有代码差距
kiro-validate-design	是	校验设计质量
kiro-validate-impl	是	校验实现结果
kiro-verify-completion	通常由流程触发，也可单独用	做最终完成校验
kiro-impl	是	进入实现阶段
kiro-review	通常由流程触发，也可单独用	做 review
kiro-debug	通常由流程触发，也可单独用	做问题排查

---

9. 安装后最常改的地方

路径	什么时候改
AGENTS.md	想改项目规则时
.kiro/settings/templates/	想改生成文档样式时
.codex/agents/*.toml	想改某个 agent 的模型或行为时

---

10. 官方地址

• GitHub：https://github.com/gotalab/cc-sdd
• npm：https://www.npmjs.com/package/cc-sdd
• README：https://github.com/gotalab/cc-sdd/blob/main/README.md
• Skill Reference：https://github.com/gotalab/cc-sdd/blob/main/docs/guides/skill-reference.md
• Customization Guide：https://github.com/gotalab/cc-sdd/blob/main/docs/guides/customization-guide.md
• Migration Guide：https://github.com/gotalab/cc-sdd/blob/main/docs/guides/migration-guide.md
• Why cc-sdd：https://github.com/gotalab/cc-sdd/blob/main/docs/guides/why-cc-sdd.md

---

11. 安全结论

基于当前项目生成文件，以及之前对 cc-sdd 仓库和发布包的静态检查：

• 没看到明显后门
• 没看到明显偷偷上传项目内容的静态证据
• 没发现明显恶意注入逻辑

真正要注意的是：它是一套高自治工作流，可能比你预期更主动。