1. 项目概述为AI编程打造一个持久化的“航海日志”如果你和我一样深度使用过 Claude Code、Cursor 这类 AI 编程助手那你一定经历过这种“失忆”的挫败感昨天和 Claude 花了两个小时从三个方案里敲定了 JWT 中间件的架构讨论了性能、安全性和可维护性的权衡。今天打开新会话一切归零。你问它“我们为什么选 JWT 而不是 Session”它只能给你一个教科书式的通用答案昨天那些具体的、属于这个项目的、充满血泪的决策过程全没了。它们散落在无法搜索的聊天记录里或者干脆被遗忘了。这就是shiplog要解决的核心痛点。它不是一个全新的工具而是一个工作流增强器。它的核心理念是将 AI 辅助编程过程中产生的所有“为什么”——那些设计决策、被否决的替代方案、中途发现的坑、临时的权衡——都变成可搜索、可追溯、可继承的资产并直接沉淀在你每天都在用的 GitHub 上Issues, PRs, Commits。你可以把它理解为给你的代码库配了一个“船长日志”记录每一次航行的决策、发现与得失。它最吸引我的地方在于其“非侵入性”和“协议化”的设计。它不试图取代git或ghCLI而是定义了一套在现有工具之上工作的“协议”。通过一系列/shiplog命令它将你与 AI 的对话自然地引导并结构化到 GitHub 的工作流中。最终你得到的不仅是一份干净的代码变更还有一份完整的、附在 PR 里的“决策时间线”以及一个未来任何 AI 模型或你的队友都能无缝接手的知识图谱。2. 核心设计思路将临时对话转化为持久化知识为什么传统的 AI 编程会“失忆”因为对话是临时的、线性的、非结构化的。shiplog的设计哲学就是打破这种临时性通过几个关键的设计选择把非结构化的聊天变成结构化的工程记录。2.1 以 GitHub 为单一事实来源很多工具喜欢自己搞一套数据库或文件格式来存储“记忆”。shiplog反其道而行之它选择 GitHub 作为所有知识的承载平台。这是一个极其聪明的决定原因有三零额外基础设施你不需要部署服务器、管理数据库。GitHub 本身就是现成的、高可用的、带完整权限系统的“记忆体”。无缝集成现有流程你的团队已经在用 Issues 跟踪任务用 PRs 做代码审查。shiplog只是让这些载体承载了更丰富的信息决策过程而不是引入一套并行的新系统。天然的搜索与链接能力ghCLI 和 GitHub 的搜索功能本身就非常强大。shiplog通过一套命名和标签规范如#ID标识符、shiplog/标签让你能轻松地跨 Issues、PRs、Commits 进行关联搜索。实操心得这个设计意味着项目的准入门槛极低。只要你的项目在 GitHub 上且你本地装了git和ghCLI几乎不需要任何额外配置就能用起来。这对于个人项目或小团队快速试验非常友好。2.2 协议优于实现shiplog将自己定位为一个“协调者”而非“全能选手”。它不重新实现git commit或gh pr create而是定义何时以及如何去调用这些命令并规定调用前后需要遵循的协议。例如它的/shiplog commit命令背后可能是一系列动作提示你为这次提交总结“为什么这么改”而不仅仅是“改了啥”。将这段上下文以特定格式如隐藏的 HTML 注释写入提交信息或一个独立的上下文文件。执行git commit -m “feat(#42/T1): 添加 JWT 验证 [上下文链接]”。更新对应 Issue 的任务进度。这个协议的核心是ID-First Convention。所有产物分支、提交、PR都通过#42这样的 Issue ID 关联任务级提交则用#42/T1标识。这就像给所有离散的信息碎片贴上了统一的条形码让后续的搜索、聚合变得异常简单。2.3 区分“安静模式”与“完整模式”这是我认为shiplog设计中最具工程实用性的特性之一它巧妙地平衡了“记录一切”的需求和“保持PR清洁”的专业要求。完整模式所有脑暴、决策上下文都直接写入主分支的 Issue 和 PR 描述中。适合个人项目或开源项目追求极致的可追溯性。安静模式团队看到的 PR 依然是干净、简洁的技术描述。而所有的原始讨论、决策权衡、试错记录都被保存在一个独立的feature/auth-middleware--log分支里。审查者只需点击一个链接就能看到完整的“幕后故事”。这种设计承认了一个现实在团队协作中过于冗长的 PR 描述可能会降低审查效率。但你又绝不想丢失这些宝贵的上下文。“安静模式”提供了一个两全其美的方案。3. 核心工作流与实操解析shiplog将一个功能从构思到上线的过程抽象为六个阶段并提供了对应的命令来引导。我们来拆解每个阶段具体发生了什么以及你该如何操作。3.1 阶段一计划 —— 从脑暴到可执行的 Issue当你有一个新功能想法时不再是在聊天窗口里和 AI 空谈。你使用/shiplog plan 我们需要一个用户认证中间件。背后发生了什么shiplog会引导 AI通常是高推理能力的 Tier-1 模型如 Claude Opus进行结构化讨论。讨论输出会被格式化为一个标准的 GitHub Issue包含清晰的需求描述。考虑的备选方案及其权衡例如JWT vs. Session Cookies各自的优缺点。初步的任务分解T1: 设计接口 T2: 实现 JWT 签发 T3: 实现验证中间件...。自动打上shiplog/plan标签。在 Issue 描述中以隐藏的 HTML 注释形式包含机器可读的元数据如Authored-by: claude/opus-4.6。你的操作和收获操作只需发起一个自然语言指令。shiplog会接管后续与 AI 的交互并最终在 GitHub 上创建 Issue。收获一个永久的、可搜索的设计文档。一周后当你或另一个 AI 模型看到#42能立刻理解当初的决策背景而不是重新发明轮子。3.2 阶段二开始工作 —— 创建隔离的工作环境Issue 创建好后你执行/shiplog start #42。背后发生了什么shiplog读取 Issue#42的所有内容包括隐藏的元数据将其作为上下文加载给 AI。在后台它使用git worktree为这个 Issue 创建一个独立的工作目录和分支例如feature/auth-middleware。你将当前终端环境切换到这个全新的工作树。这意味着你可以同时开展多个功能的工作而互不干扰这是git worktree的经典用法shiplog将其自动化了。实操要点工作树隔离这是保证上下文纯净的关键。在这个工作树里AI 助手只“看到”与#42相关的文件和上下文避免了其他无关修改的干扰。上下文继承AI 助手从一开始就“知道”整个计划不需要你复述。这极大地提升了效率。3.3 阶段三与四执行与提交 —— 记录“为什么”而不仅仅是“做了什么”在编码过程中你会不断执行/shiplog commit。与普通git commit的核心区别引导式提交信息shiplog会提示你“除了代码变更还有什么重要的发现或决策需要记录吗” 这迫使你或 AI思考并记录上下文。结构化记录这些上下文可能被追加到提交信息中或以注释形式写入代码更重要的是它会作为一条“时间线评论”被记录到该分支的shiplog追踪文件中。任务关联提交信息会自动关联 Issue 和任务如feat(#42/T2): 实现JWT签发逻辑。这让进度跟踪自动化。最强大的部分发现协议编码中常会发现计划外的问题比如你发现使用的加密库有个隐蔽的线程安全问题。传统做法是要么默默修了要么在代码里加个// TODO然后大概率被遗忘。shiplog的发现协议会介入引导你对这个发现进行分类和路由小修复30分钟直接就地修复并在时间线中记录一笔“发现库X的线程安全问题已通过Y方式规避”。前置阻塞问题创建一个新的、标记为shiplog/blocker的 Issue#43并基于#42的代码创建一个堆叠分支。#42的 PR 将等待#43合并。独立重要问题创建一个新的 Issue#44打上shiplog/discovery标签然后继续当前工作。这个发现不会被淹没在聊天记录里。重构机会创建标记为refactor的 Issue留待日后处理。这个协议确保了没有发现会丢失所有中途产生的智慧都被妥善安置。3.4 阶段五交付 —— 生成讲述完整故事的 PR功能开发完成你运行/shiplog pr。生成的 PR 描述将是这样的标准摘要功能是什么。决策时间线核心价值[计划]链接到原始 Issue#42概述初始方案。[发现-2024-05-27]在实现 T2 时发现加密库的线程安全问题链接到#43。[决策]决定采用备用方案 B因为方案 A 存在性能瓶颈链接到相关讨论上下文。[完成]所有任务T1, T2, T3均已完成并通过了验证测试。证据链接关联所有相关的提交和子 PR。验证摘要概述执行了哪些测试根据.shiplog/verification.md配置。这样的 PR不仅告诉审查者“改了哪些代码”更清晰地讲述了“为什么这些代码长成这样”极大提升了审查效率和质量。3.5 阶段六搜索 —— 在知识图谱中定位信息之后当你想知道“我们当初为什么选择这个 JWT 库”时你可以使用gh issue list --search “JWT”查找设计讨论。使用git log --all --oneline --grep”#42”查找所有相关提交。或者直接使用/shiplog lookup JWT 库 选择让shiplog帮你进行跨 Issue、PR、Commit 的联合搜索。4. 高级特性深度解析4.1 跨模型审查打破“自我认证”的循环这是shiplog在保证代码质量方面最关键的机制。它强制要求任何 PR 在合并前必须经过一个不同的 AI 模型或人类的审查。为什么这很重要同一个 AI 模型生成代码然后自己审查自己的代码这无异于“自我认证”极易遗漏它自身思维模式下的盲点。不同的模型如 Claude 和 GPT有不同的“思维倾向”跨模型审查能有效模拟同行评审发现更多问题。如何工作当作者模型如 Claude Sonnet创建 PR 后shiplog会触发审查流程。它可能调用配置中的另一个模型如 GPT-4o将 PR 上下文、代码变更和审查要求传递过去。审查模型会生成带有Reviewed-by:签名的审查意见可以是“批准”、“附带修改建议批准”、“请求变更”或“仅评论”。这些审查意见会作为评论添加到 PR 中形成审计轨迹。实操配置你需要在.shiplog/routing.md中配置模型层级和审查规则。例如# .shiplog/routing.md tier-1: models: [claude-opus, o3-mini] for: [brainstorm, design, pr-synthesis] tier-2: models: [claude-sonnet, gpt-4o] for: [implementation, code-review] tier-3: models: [claude-haiku, gpt-4o-mini] for: [routine-commits, refactoring] cross-review-policy: required # 强制要求跨模型审查4.2 模型层级路由与委托合同不是所有任务都需要最强大、最贵的模型。shiplog支持根据任务阶段自动路由到不同“层级”的模型并在模型间交接时生成明确的“委托合同”。工作流程示例Tier-1 (Claude Opus)完成架构设计并拆解出“实现用户登录API”这个具体任务。当需要执行这个任务时shiplog提示“是否将任务#42/T2委托给更快的 Tier-3 模型如 Claude Haiku执行”如果你同意Tier-1 模型会生成一份委托合同内容可能包括允许修改的文件/src/auth/api.py,/src/auth/schemas.py禁止更改的文件/src/auth/core/jwt.py核心逻辑不变停止条件如果遇到数据库连接错误立即停止并上报。验证要求实现后必须通过red-green验证配置文件中的单元测试。决策预算0。意味着 Tier-3 模型不能做任何架构或设计决策只能严格按合同执行。这份合同连同任务上下文一起交给 Tier-3 模型。Tier-3 模型在严格的约束下高效完成编码工作。这样做的好处是既利用了小型模型的快速响应和低成本优势又通过合同保证了执行过程不会偏离核心设计意图实现了成本与质量的控制。4.3 验证配置文件可携带的质量门禁.shiplog/verification.md文件定义了一系列可组合的测试策略。这些策略可以绑定到项目、特定 Issue 甚至单个任务上。示例配置# .shiplog/verification.md default-profile: [red-green, structural] profiles: red-green: steps: - run: pytest --lf -x if: *.py in changed_files structural: steps: - run: pylint --fail-under8.0 on: [src/] - run: mypy --strict on: [src/] behavior-spec: steps: - prompt: “请根据ACCEPTANCE_SCENARIOS.md中的场景验证当前实现。如有不符需申请变更合同。” ask-before-changing: true当一个任务被委托给 Tier-3 模型时合同里会写明“必须通过red-green和structural验证”。模型在执行完代码后会自动运行这些检查确保代码质量符合预设标准。这相当于为每一次 AI 编码任务都配备了自动化的质量门禁。5. 安装、配置与日常使用指南5.1 安装与初始化最推荐的方式是通过npx skills安装这适用于 Claude Code、Codex 和 Cursor 环境。# 一键安装 npx skills add devallibus/shiplog --skill shiplog # 如果你有多个AI助手环境可以指定安装到某一个 npx skills add devallibus/shiplog --skill shiplog --agent claude-code # 后续更新 npx skills update安装前提GitHub CLI (gh)必须安装并已通过gh auth login认证。这是shiplog与 GitHub 交互的桥梁。Git你的项目必须是一个 Git 仓库并且已关联 GitHub 远程仓库。安装后在你的 AI 助手如 Claude Code中输入/应该就能看到shiplog相关的命令了。5.2 基础配置可选但推荐虽然shiplog可以零配置运行但进行一些简单配置能极大提升体验。1. 模型路由配置 (.shiplog/routing.md)在项目根目录创建此文件定义你的模型偏好。这能确保在正确的阶段调用正确的模型优化成本和效果。# .shiplog/routing.md # 定义模型层级 tiers: tier-1: name: 架构师 models: [claude-3-5-sonnet, claude-3-opus] # 用于复杂设计和决策 auto-route-to: [brainstorm, plan, synthesize] tier-2: name: 工程师 models: [gpt-4o, claude-3-haiku] # 用于主要编码和审查 auto-route-to: [implement, review] tier-3: name: 助手 models: [gpt-4o-mini] # 用于机械性任务和补全 auto-route-to: [routine, refactor, test] # 审查策略 cross-review: required: true # 强制跨模型审查 # 允许同层级内审查的例外情况例如两个不同的tier-2模型 allow-within-tier: false # 默认委托行为 delegation: ask-before-delegating: true # 委托前询问确认 default-decision-budget: 0 # 默认不允许被委托方做设计决策2. 验证配置 (.shiplog/verification.md)定义你的质量检查标准。这个文件是“可继承”的项目级的配置会被所有 Issue 继承但某个 Issue 可以定义更严格的规则。# .shiplog/verification.md # 默认验证组合项目级 default-profile: [lint, unit-test] profiles: # 基础代码风格检查 lint: steps: - run: black --check . if: *.py in changed_files - run: ruff check . if: *.py in changed_files # 单元测试红绿测试 unit-test: steps: - run: pytest -xvs if: any(f.endswith(_test.py) for f in changed_files) # 行为驱动开发验收测试 acceptance: steps: - prompt: “请对照BEHAVIOR.md中的场景逐一验证功能。任何偏差都需要记录并申请变更。” ask-before-changing: true # 重要要求助手在修改行为前必须确认 # 针对安全相关任务的强化检查 security: inherits: [lint, unit-test] # 继承基础检查 steps: - run: bandit -r src/ if: auth in changed_files or user in changed_files5.3 日常使用命令速查安装后你主要通过一系列/shiplog开头的命令来工作场景命令说明与技巧开始一个新功能/shiplog plan 实现用户消息推送功能最好用 Tier-1 模型执行。描述尽量具体AI 会引导你补充细节。开始编码/shiplog start #58确保你在项目根目录。这会创建一个独立的工作树环境是干净的。提交代码/shiplog commit关键习惯不要只写“修复bug”。务必在提示下用一两句话记录为什么这么改遇到了什么坑。中途遇到问题系统会自动触发发现协议根据弹窗提示选择小修复、创建阻塞 Issue、创建独立 Issue。这是避免上下文丢失的关键。完成功能发起PR/shiplog pr在功能分支上执行。PR 描述会自动生成记得检查一下时间线是否准确。切换工作上下文cd /path/to/main/worktree或cd /path/to/feature/worktree使用git worktree list查看所有工作树。shiplog帮你管理但切换需要手动cd。查找历史决策/shiplog lookup 为什么用Redis而不用Memcached比直接用gh搜索更强大它能关联上下文。查看接下来做什么/shiplog hunt让 AI 分析所有 open 的 Issue 和 PR推荐优先级最高的工作。注意事项/shiplog commit和/shiplog pr依赖于你当前所在的工作树和分支。务必在正确的shiplog创建的工作树目录下执行这些命令否则会找不到上下文。5.4 与现有技能/插件协同shiplog被设计为“胶水”它可以和很多现有技能组合形成更强的工作流。例如你可以结合ork:commit来生成更规范的提交信息或者用superpowers:brainstorming来进行更发散的设计讨论。安装这些配套技能后shiplog会在相应阶段自动调用它们无需你手动干预。6. 常见问题与故障排查在实际使用中你可能会遇到以下问题。这里是我踩过坑后总结的解决方案。6.1 安装与命令找不到问题安装了shiplog但在 AI 助手界面输入/看不到相关命令。检查安装路径确认技能被安装到了正确的 AI 助手目录。对于 Claude Code全局路径是~/.claude/skills/项目内路径是.claude/skills/。检查shiplog文件夹是否存在。重启 AI 助手有时需要重启 Claude Code 或 Cursor 的会话才能加载新技能。手动复制命令如果技能加载了但命令没有可以尝试手动复制命令文件cp -r /path/to/shiplog/commands/shiplog ~/.claude/commands/。问题执行命令时报错提示gh命令未找到或未认证。确保ghCLI 已安装在终端运行gh --version确认。运行gh auth login完成 GitHub 认证。shiplog的所有 GitHub 操作都依赖于此。检查仓库远程确保当前 Git 仓库已关联 GitHub 远程仓库 (git remote -v)。6.2 工作流执行错误问题/shiplog start #xx失败提示找不到 Issue 或创建分支失败。确认 Issue 号确保#xx是存在于当前仓库的 Issue 编号。你可以先用gh issue list查看。检查仓库状态确保当前仓库没有未提交的更改或者这些更改可以暂存/丢弃。一个“脏”的工作区有时会干扰工作树的创建。手动清理如果之前shiplog运行异常中断可能会残留孤立的工作树。使用git worktree list查看并用git worktree remove /path/to/worktree手动清理然后重试。问题/shiplog commit提交的信息格式不对或者没有关联到 Issue。检查当前分支确保你正在由shiplog start创建的功能分支上。使用git branch --show-current确认。检查分支命名shiplog创建的分支名通常包含 Issue 号。如果分支名被手动修改过可能导致关联失败。查看.shiplog/目录在项目根目录或工作树目录下看看是否有shiplog生成的临时上下文文件它们可能记录了状态。问题跨模型审查没有触发。检查路由配置确认.shiplog/routing.md中cross-review: required: true。检查模型可用性确保你配置的审查模型在你的 AI 助手环境中是可用的例如你在 Cursor 里配置了 Claude 审查但 Cursor 当前可能只接了 GPT。查看 PR 描述有时审查是异步的或者以评论形式添加。检查 PR 的评论区域看看是否有来自其他模型的Reviewed-by:签名。6.3 性能与成本顾虑问题感觉shiplog让流程变复杂了每次提交都要写上下文拖慢速度。心态转变这类似于写测试——短期看增加时间长期看节省大量调试和重构时间。对于复杂或重要的变更记录上下文是值得的。对于琐碎的修改你可以选择快速提交不记录详细上下文。善用“安静模式”如果你在团队中工作启用“安静模式”。这样你的详细记录只在--log分支主 PR 保持简洁兼顾了效率和追溯性。问题使用 Tier-1 模型如 Claude Opus进行脑暴和设计成本会不会很高分层使用这正是模型路由的价值。只用 Tier-1 做最核心的设计和决策。大量的实现、代码补全、文档编写交给 Tier-2 或 Tier-3 模型。shiplog的委托合同能保证低成本模型不“跑偏”。投资回报一次性的、高质量的设计文档其价值远超过模型调用成本。它避免了未来的重复讨论和错误决策。6.4 团队协作与习惯培养问题团队中只有我一个人用shiplog会不会产生沟通隔阂“安静模式”是答案这是为此场景设计的。你提交的 PR 看起来和往常一样干净。只有当队友对某个决策有疑问时你可以说“详细的决策过程我记录在--log分支了链接在这里。” 这实际上提供了比口头解释更清晰的文档。逐步推广可以先在个人项目或团队的非关键项目上试用展示其价值如减少重复问题、 onboarding 新人更快。用实际生成的、高质量的 PR 时间线来说服队友。问题生成的 Issue 和 PR 描述太长队友不爱看。优化记录习惯记录上下文时力求简洁、重点突出。不是记流水账而是记录关键的转折点、决策依据和发现的坑。使用列表和加粗强调关键信息。利用标签和标题shiplog自动添加的标签如shiplog/decision,shiplog/discovery可以帮助队友快速筛选他们关心的部分。7. 个人实践心得与进阶技巧用了几个月shiplog后它已经深度融入我的开发流程。分享一些超出官方文档的实战心得。1. 把“发现协议”当作最重要的习惯来培养。最初我常常忽略中途发现的小问题想着“先记在脑子里做完这个再说”。结果就是 90% 都会忘。强制自己使用shiplog后每当发现一个计划外的问题我会立刻暂停根据发现协议的引导做出选择。这个微小的停顿拯救了无数个后来需要熬夜排查的 Bug。现在我的每个功能分支的--log里都充满了“发现XXX决定YYY因为ZZZ”的记录这比任何事后补的文档都有价值。2. 自定义验证配置文件是质量的“安全带”。不要满足于默认配置。根据你的项目特点定制.shiplog/verification.md。比如我的前端项目配置了eslint和stylelint检查Node.js 项目配置了npm audit数据管道项目则配置了特定的数据模式验证脚本。当 AI 助手特别是 Tier-3完成代码后自动运行这些检查能拦截大部分低级错误和风格问题让我在审查时能更专注于逻辑和架构。3. 委托合同写得越细后期麻烦越少。当把任务从 Tier-1 委托给 Tier-3 时最初我写的合同很粗略“实现这个函数”。结果 Tier-3 模型有时会“自作主张”地修改接口或引入不必要的依赖。后来我学会了写“零决策预算”的严格合同精确的文件路径只允许修改src/utils/dateFormatter.js。明确的输入输出函数必须接受 ISO 字符串返回本地化格式字符串。禁止区域不得修改任何导入语句不得添加新的依赖。停止信号如果遇到日期解析异常直接抛出错误new FormatError()不要尝试修复。 这样Tier-3 模型就变成了一个高度可控的“代码生成器”产出非常稳定。4. 将/shiplog hunt作为每日站会的输入。每天早上开工前运行一下/shiplog hunt。让 AI 分析当前所有 Issue 和 PR 的状态、依赖关系、过期时间然后给我一个优先级排序的工作建议。这比我自己看看板要高效得多因为它能理解“#58阻塞了#62”这样的上下文。我甚至把它集成到了团队的 CI 流程中每天自动生成一份报告发到 Slack。5. “证据链接闭环”让项目管理更踏实。shiplog要求关闭 Issue 时必须链接证据合并的 PR、特定的 Commit。这个强制约束彻底杜绝了“我以为我做了”的情况。作为项目负责人我现在只需要定期检查那些没有关联 PR 就被关闭的 Issue这几乎总能发现一些被遗漏的工作。它建立了一种良性的责任追溯文化。6. 知识图谱的长期价值在“重构”和“答疑”时爆发。上周我需要重构一个一年前写的消息队列模块。如果没有shiplog我需要重新阅读所有相关代码猜测当时的意图。而现在我只需/shiplog lookup 消息队列 选型立刻就能找到当时的 Issue里面详细记录了为什么选择了 RabbitMQ 而不是 Kafka当时资源限制以及实现过程中遇到的连接池问题及解决方案。为新成员答疑也是如此我直接发一个链接给他比我自己回忆和复述要准确、全面得多。shiplog本质上是一种工程纪律的具象化。它通过工具强制你养成记录、关联、验证的好习惯。一开始可能会觉得有点束缚但一旦适应你会发现它从“负担”变成了“靠山”。你不再需要记住所有细节也不再害怕 AI 助手的“失忆”。你和 AI 的协作变成了一场有迹可循、步步为营的接力赛而不是在迷雾中的随机漫步。对于任何严肃使用 AI 进行软件开发的个人或团队我认为它都是值得深度集成的基础设施。