123 lines
9.3 KiB
Markdown
123 lines
9.3 KiB
Markdown
# Coding Skills
|
||
|
||
两个中文工程 skill，用精简的当前决策保持目标一致，并将规划与实施放在不同会话。
|
||
|
||
| Skill | 用途 | 产出 |
|
||
| --- | --- | --- |
|
||
| `align-plan` | 调查代码、每轮提问 1–3 个问题、核对假设并收敛范围 | 系统约束、当前决策与用户确认后的可执行计划 |
|
||
| `execute-plan` | 按已确认计划实施、验证、核对范围和 review | 外部实施记录与本地 Git commit |
|
||
|
||
## 安装
|
||
|
||
仓库采用 `skills/<名称>/SKILL.md`，每个入口包含 `name` 和 `description`，可由 [skills CLI](https://github.com/vercel-labs/skills#creating-skills) 发现。没有运行时依赖，无需插件清单。
|
||
|
||
通过 Gitea SSH 地址安装全部 skill：
|
||
|
||
```sh
|
||
npx -y skills add ssh://git@gitea.fjy8018.top:8022/fjy8018/coding-skills.git --skill '*'
|
||
```
|
||
|
||
需要已配置可访问该仓库的 SSH 密钥。两个 skill 也可单独安装，将 `'*'` 替换为 `align-plan` 或 `execute-plan` 即可。安装时由 CLI 选择目标 agent。
|
||
|
||
## 使用
|
||
|
||
两个 skill 仅在用户明确调用时启用。Codex 中可使用 `$align-plan`、`$execute-plan` 或通过 skill 选择器调用；普通“规划方案”“执行任务”请求不自动启用。
|
||
|
||
在项目目录中开始规划，例如：
|
||
|
||
```text
|
||
$align-plan 目标是修复订单查询的分页重复问题。
|
||
本次保留现有接口格式。讨论资产放到 /绝对路径/工程讨论。
|
||
```
|
||
|
||
Agent 先调查再提问，纠正有证据的错误判断，每轮维护精简的当前决策。范围明显变大时，会提出分阶段建议供用户选择。关键问题解决后，先将完整计划写入文件并标为“待确认”，对话只给简短摘要和文件链接。用户自行读取文件审阅，确认后将该计划标为已批准。
|
||
|
||
计划列出修改文件、目标、原因和验收要求，不预写详细实现代码。核心算法可附少量代码或伪代码帮助审查；具体实现由执行 agent 在已批准的行为和架构边界内自主决定。
|
||
|
||
方案与实施遵循最小改动、单一职责和开闭原则，按需采用设计模式；保持功能模块边界，通用架构能力不绑定具体业务，避免为套模式增加抽象，以降低扩展和审查复杂度。
|
||
|
||
最小改动不等于最少行数或继续堆叠旧逻辑。发现与目标相关的复用提取或模块解耦机会时，agent 会说明收益、成本和影响范围，向用户确认后再纳入计划。
|
||
|
||
审阅确认后自行开启新会话，指定已批准的计划：
|
||
|
||
```text
|
||
$execute-plan 执行 /绝对路径/工程讨论/2026-09-10-pagination-fix/plan.md
|
||
```
|
||
|
||
支持命令式调用的宿主也可使用对应的 skill 命令，具体语法以宿主为准。Skill 不负责自动创建新会话，也不能保证检测或清除旧上下文。
|
||
|
||
Codex 默认根据 `description` 隐式选择 skill；本仓库在每个 skill 的 `agents/openai.yaml` 中设置 `policy.allow_implicit_invocation: false`，保留显式调用。仅修改描述不能代替该策略。[官方调用策略说明](https://learn.chatgpt.com/docs/build-skills)
|
||
|
||
更新已有安装时须同步整个 skill 目录，包括 `agents/openai.yaml`，不能只替换 SKILL.md。若仍出现旧行为，检查项目级、用户级同名副本，重启 Codex 并在新会话验证；更新配置不会撤回旧会话已加载的正文。其他宿主是否支持此策略需单独确认，不保证仅靠描述就能禁止自动加载。
|
||
|
||
执行时允许增加必要测试或配置文件并说明理由；涉及业务、接口、架构或其他范围扩展时，需更新计划并确认。验证和 review 通过后创建本地提交，不 push。
|
||
|
||
实施时核实引用与兼容用途，移除范围内无用的死代码和被替代的遗留实现。若核心假设、业务语义或架构边界与决策有重大出入，立即停止执行并记录现场，建议回到 align-plan 重新对齐范围和边界；重新确认前不继续实现。
|
||
|
||
计划预先评估兼容性，执行结果根据实际改动复核接口、数据、配置及新旧版本影响。结果明确是否需要特殊上线步骤和顺序；需要时提供前置条件、顺序、验证点及必要回退限制，无需时明确说明，未知项如实标注。上线评估不等于实际部署授权。
|
||
|
||
## 资产约定
|
||
|
||
首次未指定资产目录时会询问；之后从项目 `.agent/MEMORY.md` 复用。这个文件只保存必要定位信息，通过 Git 本地 exclude 排除，不修改项目共享 `.gitignore`。已被跟踪时会先报告冲突，不自行取消跟踪。
|
||
|
||
讨论资产严格使用用户选择的代码库外部目录，可按计划建立一层子目录，不添加项目名或系统名中间层。用户已指定本次计划目录时直接使用：
|
||
|
||
```text
|
||
资产根目录/
|
||
CONTEXT.md 当前业务与技术约束、模块
|
||
日期-计划主题/
|
||
current.md 当前目标、确认决策、约束与未决问题
|
||
plan.md 最新自包含计划，原地修订、审阅确认
|
||
execution-日期时间.md 实施与验证记录
|
||
```
|
||
|
||
每个计划目录只维护 plan.md，修订直接覆盖，只保留最新方案，不生成版本副本或历史方案。实质修订清除旧批准依据并标为待确认，用户重新审阅后再执行。对话只给摘要和链接，写入成功不代表批准。current.md 同样只维护当前讨论状态，不累计历史。目录失效或无法写入时会报告，不自行改存代码库。个人绝对路径不写入可分发的 skill。
|
||
|
||
两个 skill 在确定资产根目录后都先读取 `CONTEXT.md`，再针对本次目标核实相关代码；新会话或上下文恢复时同样读取，无需扫描历史计划。根目录默认对应一个系统；若文档属于其他系统，先澄清。用户只指定计划目录时，保留已知系统根目录，未知则询问，不推断父目录。
|
||
|
||
`CONTEXT.md` 只描述当前有效的业务约束和技术约束，可注明适用模块及必要原因。无需实施的已确认规则直接更新；依赖改造的方案暂留在讨论和计划中，经实施、验证和 review 完成后再更新 CONTEXT。冲突先确认，替换时删除废弃规则，不保存中间决策、状态历史或关联历史计划路径。
|
||
|
||
该文件不记录任务清单、实现代码、日志或完整历史。`current.md` 保留本次讨论与未决问题；计划保留本次相关约束的快照，执行记录保存进度和证据。CONTEXT 不存在时从首次确认的长期约束开始建立，不回扫历史计划。执行 agent 的局部实现选择不自动变成系统约束。
|
||
|
||
每份生成的 Markdown 资产（包括本地 MEMORY）顶部保留以下 YAML 元数据：
|
||
|
||
```markdown
|
||
---
|
||
系统:
|
||
时间: 2026-09-08
|
||
目标:
|
||
---
|
||
```
|
||
|
||
系统填写项目或系统名称，目标概括对应计划的目标，无法确定时留空。时间对应资产所依据的决策，使用用户当地日期。未确认草稿先记创建日期，正文标明待确认；确认后更新为确认日期。计划重新批准后使用新确认日期；实施记录沿用计划决策日期，执行时间单独记录。纯进度或排版更新不改决策日期。
|
||
|
||
CONTEXT 的目标填写“保存系统当前业务与技术约束”，时间为最近一次确认系统决策的日期；普通排版更新不修改该日期。
|
||
|
||
## 验证
|
||
|
||
结构检查：
|
||
|
||
```sh
|
||
npx skills add . --list
|
||
```
|
||
|
||
预期仅发现 `align-plan` 和 `execute-plan`。若已安装 skill-creator，可用其 `scripts/quick_validate.py` 分别检查两个 skill 目录；它是开发期检查工具，不是安装或运行依赖。
|
||
|
||
行为检查应使用真实 agent 在隔离项目中演练：目录首次询问与复用、错误假设纠正、长对话恢复、目标分阶段、批准前不实现、新会话交接、必要配套文件与范围扩展的区别、过期计划、测试覆盖与重复、已有用户修改及提交隔离。
|
||
|
||
系统上下文还需检查：首次无 CONTEXT、下次直接读取、无实施依赖的确认规则直接记录、待实施方案只留计划、冲突澄清、执行失败不改当前约束、验证后替换废弃规则、局部实现细节不写入系统约束。
|
||
|
||
结构验证只能检查格式和可发现性；静态场景复核只能发现指令缺口。两者都不证明模型实际遵循工作流，实际行为需要另行记录演练证据。不要把文字规则当作宿主级权限隔离。
|
||
|
||
## 参考来源
|
||
|
||
独立编写本仓库指令，借鉴以下机制，不复制其完整工作流，也不要求安装这些项目：
|
||
|
||
- [Ponytail](https://github.com/DietrichGebert/ponytail)：理解问题后，优先复用并选择满足目标的最小实现。
|
||
- [Superpowers](https://github.com/obra/superpowers)：参考 brainstorming 的确认边界、writing-plans 的文件与验证说明、executing-plans 的计划复核。
|
||
- [Matt Pocock Skills](https://github.com/mattpocock/skills)：参考 grill-me / grilling 的先调查事实、再讨论决策。这里限制每轮 1–3 问，以目标和验收收敛，不要求穷尽所有分支。
|
||
|
||
另外参考 [domain-modeling](https://github.com/mattpocock/skills/blob/main/skills/engineering/domain-modeling/SKILL.md) 在讨论中持续沉淀的机制。上游 CONTEXT 限于术语表、设计决策另存 ADR；本项目按需要将当前业务与技术约束直接保存在外部 CONTEXT，不引入 ADR 框架。
|
||
|
||
上游工作流会变化；本仓库的实际规则以两个 `SKILL.md` 为准。
|