CraftKit 协作约定

本文件适用于 CraftKit 仓库及其全部子目录。更深层目录若存在自己的 AGENTS.md，以更具体的约定为准。

项目目标

CraftKit 面向 Codex 插件市场，提供简洁、中性、可独立安装和维护的 Skill。每项能力都应具备清晰边界，并能够独立理解与验证。

项目资料

结构化项目配置：.craftkit/project.json
Agent 补充说明：.craftkit/agents/index.md
项目规范索引：.craftkit/standards/index.md
项目知识索引：.craftkit/knowledge/index.md

沟通与改动

所有回答、文档和代码注释使用中文；公开 API、标准名称和代码标识可以保留英文。
修改前先说明方案。简单改动可在说明后直接执行；复杂或高风险改动先明确范围、影响和验证方式。
阅读、分析和评审任务默认只读，不因发现问题自动扩大为修改任务。
未经明确要求，不提交、不推送、不安装插件，也不修改用户级 Codex 配置。
保留工作区已有改动；提交时只暂存本次确认范围内的文件。

目录职责

路径	职责
`.agents/plugins/marketplace.json`	CraftKit 市场及插件入口
`plugins/dev/`	软件设计、编码、审查与测试 Skill
`plugins/doc/`	文档转换、整理与写作 Skill
`plugins/git/`	Git 操作与交付 Skill
`plugins/knowledge/`	交接、复盘与知识维护 Skill
`plugins/skill/`	Skill 与项目规范辅助工具

Skill 设计规则

Skill 名称使用小写字母、数字和连字符，简短且以动作或明确领域为中心。
Skill 文件夹名必须与 SKILL.md frontmatter 的 name 完全一致。
description 只说明能力和触发场景，避免大而全、宽泛兜底或堆砌关键词。
SKILL.md 只保留共同目标、关键流程和必要边界；条件性细节放入 references/。
只有重复执行且确定性逻辑明显时才新增 scripts/；新增脚本必须有可运行验证。
只有产物确实需要模板、图片或样例文件时才新增 assets/。
不创建没有实际用途的空目录、占位文档或重复 README。
自动发现保持默认开启；只有用户明确要求时才设置为仅显式调用。

推荐结构：

plugins/<plugin>/skills/<skill>/
├─ SKILL.md
├─ agents/openai.yaml      # 有 UI 元数据时使用
├─ scripts/                # 有确定性自动化时使用
├─ references/             # 有条件加载的详细资料
└─ assets/                 # 生成产物需要的素材

维护原则

以当前 Codex 能力、项目实际情况、公开标准和用户需求为依据设计 Skill。
技术规则应注明适用版本；依赖外部资料时记录资料入口和验证日期。
新增内容应具备明确用途，避免重复能力、过期说明和仅用于记录开发过程的文档。

新增与修改流程

阅读目标插件、相邻 Skill、适用的 AGENTS.md 和当前 Git 状态，确认职责边界与已有改动。
明确用户目标、输入、输出、触发条件、副作用、权限和不包含事项。
检查是否应复用或扩展已有 Skill，避免名称不同但职责重复的实现。
修改前向用户说明目标文件、实现方式、风险和验证方法；高风险或范围不明确时等待确认。
按最小必要结构实现，优先使用项目证据和官方资料，不猜测接口、版本或运行行为。
完成结构、引用、插件清单及必要行为验证，并分别记录通过项和未验证边界。
展示实际变更、验证结果、剩余风险和建议提交信息；只有用户明确授权后才执行本地提交。

CraftKit 项目目录

.craftkit/ 是项目级 Agent 配置、规范、知识和运行状态的统一目录，目录名固定为全小写；不能把整个目录视为本地缓存或整体排除。
可共享内容包括 project.json、agents/、standards/、knowledge/ 和 handoff/，可以根据用户确认正常提交和同步。
project.json 记录项目类型、技术栈、源码与包边界、内部依赖标识、常用命令和规范入口；不得记录凭据、完整连接信息或个人机器绝对路径。
成熟项目优先延续已有且有充分证据的风格；空项目根据需求、用户选择和已授权参考建立最小上下文，不自行猜测框架、包名或内部依赖。
引用其他项目时先确认参考范围，只提炼结构、依赖、命名、测试、规范或工具约定；共享配置优先记录相对路径，不能共享的本地位置放入 local/。
公共框架版本差异由 CraftKit 公共 profile 维护；项目在 project.json 选择实际版本和 profile，并在 standards/ 保存项目补充规则。
agents/ 保存项目对特定 Agent 的补充说明；standards/ 保存项目开发规范；knowledge/pitfalls/ 保存经验证且可复用的问题经验；knowledge/decisions/ 保存重要技术决策。
本地内容统一放入 local/，缓存统一放入 cache/。.craftkit/.gitignore 必须排除 /local/ 和 /cache/，但不得排除整个 .craftkit/。
本地交接默认位于 .craftkit/local/handoff/current.md；只有用户明确选择共享时才写入 .craftkit/handoff/current.md。
只在实际需要时创建目录，不一次生成空的 agents/、standards/、knowledge/、handoff/、local/ 或 cache/。
Git Skill 默认排除 .craftkit/local/** 和 .craftkit/cache/**；其他 .craftkit 内容按普通项目资产评估，并在提交建议中单独标识。
如果本地目录已经被 Git 跟踪，或整个 .craftkit/ 被全局规则、.git/info/exclude 或项目规则忽略，应提示冲突并停止自动处理；不得自动修改索引或历史。
.craftkit/ 不得保存凭据、令牌、私钥、个人机器绝对路径或无必要的个人信息。

验证要求

每个新增或修改的 Skill 至少完成：

检查目录名、frontmatter、引用路径和工具名称。
运行仓库现有的 Skill 校验器及所属插件校验器。
检查凭据、无效路径、未替换占位符和无效工具名称。
有脚本时运行核心行为测试；有生成物时检查实际产物。
以真实请求检查触发边界、权限边界和输出是否符合描述。

静态检查通过不代表真实行为已经验证，交付时应分别说明静态校验、脚本测试和实际场景验证结果。

Git 约定

使用 Conventional Commits，提交说明使用中文。
推荐类型：feat、fix、docs、refactor、test、chore。
提交前执行 git status --short、git diff --cached --check 并检查暂存文件清单。
不提交本地配置、凭据、缓存、运行产物和 IDE 私有状态。
不使用破坏性历史改写，也不推送，除非用户明确授权。

分支与发布约定

一个完整主题使用一个短生命周期开发分支；分支只包含同一能力闭环，不为凑版本混入无关变更。
分支命名优先遵循仓库现有约定；没有更具体规则时使用 feature/<short-name>、fix/<short-name>、docs/<short-name> 或 chore/<short-name>。
工作区不干净、当前 checkout 被 IDE/服务/测试占用，或用户要求不影响主工作区时，使用独立 Worktree。分支任务完成后必须通过安全清理门禁移除额外 Worktree，保留分支和提交。
已验证的开发分支合入 master 后，先在 CHANGELOG.md 的 Unreleased 累计；形成一组相关、完整、可交付的能力后再发布，不因每次普通修改单独发版。
阻断性缺陷、安全问题或已发布能力的明确回归可以单独发布修订版本；不得为等待批次延迟必要修复。
仓库整体版本遵循 SemVer：不兼容变化升级主版本，向后兼容的新能力升级次版本，向后兼容的问题修复升级修订版本。
dev、doc、git、knowledge 和 skill 插件清单版本按实际变化独立维护；修改某个插件的可见能力时同步评估其 plugin.json 版本。
发布前必须确认工作区、发布范围、版本号、验证证据、CHANGELOG.md、插件清单版本、标签目标和远程地址。版本提交、标签和推送分别按用户授权执行。

8.3 KiB Raw Blame History