code-init

# Code Init 为一个具体代码项目建立可执行、可维护的开发约定。此 Skill 只处理项目初始化或用户明确要求的初始化更新；日常功能开发交给项目现有流程。仅在用户明确调用 `$code-init` 时运行。 ## 先审查，再定方案 1. 确认目标目录和 GitHub 仓库。目标不明确时先定位，不凭当前工作目录或仓库名称猜测。读取适用的 `AGENTS.md`、仓库状态、现有文档、`.gitignore`、技术栈、构建与测试命令、CI、分支规则、Issue、Project 和 Release 设置。保留已有内容及无关的未提交改动。 2. 从项目规模、是否开源、协作者和发布方式出发，说明现状、缺口、拟新增或修改的文件、GitHub 设置及验证办法。区分必须现在做与有实际需求再做。编写代码、配置或修改远端设置前，先给用户看具体方案并等待批准。 3. 对会影响选择的 GitHub 功能、权限和产品规则，查当前官方文档。不要凭旧印象推断公开范围或自动化行为。用户尚未决定许可证、仓库可见性、发布渠道等重要事项时，先完成不依赖这些决定的工作，再提出一个聚焦的问题。 ## 建立文档和代码边界 按实际缺口维护文档，不机械生成全套文件： - `README.md` 面向使用者，交代产品用途、支持平台、可获得的安装方式、基本使用、限制和反馈入口。安装说明必须指向真实可用的产物或可验证的构建步骤。 - `LICENSE` 只在用户选定许可证后写入。仓库公开不等于已授权他人使用、修改或分发代码。 - 根目录 `AGENTS.md` 面向开发代理，写项目目标、代码入口、已验证的构建与测试命令、稳定的产品与数据安全约束、修改和 review 流程、GitHub 任务规则。每条规则都应能指导具体决策。不要复制用户的私人规划、凭据、当前任务清单或整篇 README。 - 项目如有可见界面、交互或前端样式，`AGENTS.md` 必须规定这些改动使用 `$shadcn` 与 `$oil-frontend`：前者负责复用或增补 shadcn/ui 组件与注册表，后者负责信息层级、交互、状态与验证策略。项目使用 shadcn/ui 时要连同 `components.json` 一起核对，缺少时按现有别名、样式目录和组件路径补上，并用 `npx shadcn@latest info --json` 验证解析结果。 - 仅当系统边界或设计决定不容易从代码看出时，建立简短的设计文档，说明关键模块、数据流、持久化位置、不可破坏的约束及其原因。行为改变时同步更新相应文档。 - 有外部贡献和反馈需求时，再增设贡献说明、Issue/PR 模板和安全报告入口。不要为填满 GitHub 社区清单而创建空文档。 `AGENTS.md` 必须规定：开始改动前读适用规则与相关代码，核对现有工作区改动；先给出范围、方法和验证计划并等用户批准；优先做局部、清晰、可维护的修改，考虑性能与失败路径；按项目实际命令验证；交付前 review；修复问题并复验后才能宣称完成。公开仓库中的规则不得泄露私人 Project 的具体规划或敏感信息。 在 `AGENTS.md` 中明确事实来源：Project 记录顺序和状态，Issue 记录需要追踪或协作的问题，PR 与 Git 历史记录代码改动，README 和设计文档记录稳定的用法与原因。不要让多个文件维护同一份任务清单。 ## 建立并验证 .gitignore 读取现有规则、已跟踪文件和未跟踪文件，再按语言、构建工具、操作系统及本地工具选择窄范围规则。忽略可再生的依赖、缓存、构建输出和本地密钥；保留源码、文档、产品资源、锁文件、CI 配置和可安全共享的 `.env.example`。不要无依据地忽略整个目录或所有图片、文档扩展名。 已有规则优先补缺，不覆盖注释和例外。`.gitignore` 不会取消已跟踪文件的跟踪；不得为了让规则生效而自行运行 `git rm --cached`、删除文件或改写历史。若发现已跟踪的敏感文件，说明风险并等待专门授权。修改后用 `git check-ignore -v --no-index` 检查代表路径，核对差异和 `git status --short`，确认没有隐藏应提交的文件。 ## 建立 GitHub 全程流程 把任务、开发、交付放在同一条可追溯的流程中，复用现有设置，避免重复系统： 1. **收集任务。**公开仓库中的用户反馈、社区协作和愿意公开的计划使用正式 Issue。内部想法和暂不公开的任务，默认放进 Private Project 的 Draft Issue。私人 Project 不会隐藏公开仓库中的正式 Issue；Draft Issue 转成正式 Issue 时才选择仓库并受该仓库的可见性约束。私人仓库中的正式 Issue 可用于需要仓库 Issue 功能的私密任务。 2. **决定是否需要 Issue。**不要规定“每次改代码必须建 Issue”。范围清楚、低风险、一次开发可完成且不需要后续跟踪的小修复，可直接开分支和 PR，在 PR 中写清问题、修改和验证。涉及用户反馈、需求讨论、跨会话工作、多个子任务、依赖、版本计划或需要长期追踪的工作，先建 Draft Issue 或正式 Issue。公开仓库中的安全敏感报告走私密渠道。没有 Issue 的改动仍须留下可审查的 PR 记录。 3. **安排工作。**用 Project 的现有 Status 管进度，不强制增加 Inbox、Ready 等选项；只有待整理与已决定的任务确实混在一起时才增加状态。Milestone 只用于仓库中有共同版本或目标的一组正式 Issue/PR。不要再用 `TODO.md` 复制任务清单。 4. **开发与验证。**从主分支建立工作分支，按获批范围实施。对改动运行相应测试、静态检查、构建和必要的真实使用验证。PR 写明动机、主要改动、验证结果和关联 Issue；没有 Issue 时直接说明背景。 5. **Review 关口。**每次开发交付都主动 review，不能等用户提醒，也不能用测试通过替代 review。至少对照原需求检查 diff、错误与边界条件、回归风险、性能、数据与隐私、文档和验证证据。小改动可简短 review，高风险或跨模块改动要深入审查。发现问题先修复并复验，review 未通过不得标记 Done、合并或开始下一个交付。若审查者与实现者是同一人，应如实说明；有合适的独立审查能力时可使用，但不强制为每次小改动启动额外代理。 6. **合入与发布。**在权限和用户授权范围内，确认 PR 检查与 review 通过后合入。核对 Issue 关闭、Project 状态和目标分支；需要向用户发布版本时再建立 Release，并验证下载产物。不要把“PR 已开”“检查通过”或“Project 已到 Done”当成已合入、已发布的证据。 在获批的初始化范围内，把上述流程落实到 GitHub：建立或复用 Project，核对可见性并关联适当仓库；按实际需要配置状态、字段和自动化；创建适用的 Issue/PR 模板；用项目已验证的命令配置 PR 上的 CI；评估主分支的保护或规则集；确认 Release 的构建与发布方式。逐项核对账号权限和现有配置，不为实现“全流程”而打开无用功能，也不在没有可运行检查时设置会永久阻塞合入的必需检查。 任何写入 GitHub 的标题、正文、分支名、提交和 PR 都按其所在仓库的公开范围检查。GitHub 设置、自动化和权限以当前官方文档和实际账号状态为准；外部操作完成后读回验证。 ## 交付与复核 完成初始化后，报告建立的规范、文档、`.gitignore` 规则、GitHub 流程与实际验证结果。明确哪些选择仍需用户决定，哪些远端步骤因权限或条件未完成。review 本次初始化产物，检查它们和现有项目一致、相互不矛盾，也没有复制私人规划。