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-under=8.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_files"5.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 进行软件开发的个人或团队,我认为它都是值得深度集成的基础设施。