人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载导读技术债Technical Debt是每个工程团队都绕不开的隐性成本一句“这个先 hack 一下之后重构”、一条“not blocking but should fix later”的评审意见往往会被淹没在对话流中最终无人跟进。IronClaw 的 Tech Debt Tracker 技能 提供了一套系统化的解决方案——通过被动检测、PR 评审扫描、显式捕获三种方式把技术债沉淀为结构化文档再通过清单展示、状态流转、承诺升级形成完整治理闭环。读完本文你将掌握该技能的全部六种工作模式、数据文件格式、严重度分级规则以及它如何与 IronClaw 的 commitment 体系triage、digest、resolution协作运转。技能定位与设计理念Tech Debt Tracker 是 IronClaw Agent OS 内置的一组“技能”Skill之一。技能以SKILL.md形式存放在仓库 skills/ 目录下每个技能都带有一段 YAML frontmatter声明名称、版本、激活条件与上下文预算。以本技能为例name: tech-debt-tracker version: 0.1.0 description: Detect and track technical debt from conversation and PR review comments. Resurface in weekly retros, promote to commitments when ready to fix. activation: keywords: - tech debt - technical debt - hack - hacky - refactor later - fixme - workaround - shortcut - should refactor - bandaid - temporary fix - show tech debt - debt backlog patterns: - (?i)(this|that) is (a |kind of )?(hack|workaround|bandaid|band-aid|shortcut|kludge) - (?i)(we |I )should (refactor|clean up|rewrite|fix) (this|that) (later|eventually|someday) - (?i)(show|list|review) (tech )?debt - (?i)(add.*tech ?debt) tags: - commitments - developer - tech-debt max_context_tokens: 1200设计理念有三点零打扰技能只在用户话语中“暗示”技术债时才被激活且被动检测模式下不打断对话流——提取是副作用不是对话的主角持久化优先所有债务条目都写入工作区文件系统projects/commitments/tech-debt/而不是停留在会话记忆中保证跨会话可追溯、可复盘与 commitment 体系打通技术债不是终点它可以在合适的时机被“升级”为正式承诺commitment进入 IronClaw 更宏观的任务追踪闭环。从源码层面看IronClaw 对技能激活条件有硬性上限约束。在 crates/domains/ironclaw_skills/src/types.rs 中定义了const MAX_KEYWORDS_PER_SKILL: usize 20; const MAX_PATTERNS_PER_SKILL: usize 5;并由ActivationCriteria::enforce_limits()在技能加载时对关键词与正则模式列表做截断truncate。本技能的 19 个关键词、4 个正则恰好都在上限内可以在运行时被完整加载。对比同目录下的 commitment-triage 技能后者因关键词列表较长在 frontmatter 中明确注释了“超出上限的条目会在解析时被静默丢弃”——这说明技能作者在编写激活条件时就需要预算好数量。同时max_context_tokens: 1200表示激活该技能时最多向模型注入 1200 token 的上下文确保技能说明不会挤占主对话预算。数据模型技术债条目长什么样所有被捕获的技术债都写入projects/commitments/tech-debt/slug.md采用 Markdown frontmatter 正文的结构。技能给出的标准模板如下--- type: tech-debt detected_at: today YYYY-MM-DD repo: current repo context if known, else null severity: high|medium|low category: refactor|performance|security|testing|documentation|architecture source: conversation source_pr: null --- # Brief title What the debt is and why it exists. ## Context What prompted the shortcut — deadline, complexity, missing knowledge. ## Proposed fix What a proper fix would look like, if discussed.字段语义字段取值说明typetech-debt固定值用于与 commitment、signal 等其他条目区分detected_atYYYY-MM-DD捕获日期用于后续“按年龄”排序和慢性债务统计repo仓库上下文或null记录债务所属仓库未知时显式写nullseverityhigh/medium/low严重度分级规则见下节categoryrefactor/performance/security/testing/documentation/architecture债务类型便于按类别盘点sourceconversation/pr-review捕获来源source_prowner/repo#123或null若来自 PR 评审记录 PR 的完整引用正文部分的三段式结构What → Context → Proposed fix刻意与标准 bug 报告的三要素对齐现象是什么、为什么会产生、正确解法是什么。即便“正确解法”当时并未讨论也保留该小节占位方便后续升级为 commitment 时直接引用。严重度分级规则技能定义了可操作的严重度判断标准而不是依赖模型主观感觉high安全捷径security shortcuts、数据完整性风险、架构违规medium代码质量问题、缺失测试、糟糕的抽象low风格问题、轻微 workaround、文档缺口。这套规则的价值在于可仲裁当同一句话被不同会话重复捕获时严重度不会漂移当用户在清单中质疑分级时也可以对照规则给出依据。Mode A被动检测核心工作模式当用户说出暗示技术债的话——例如“this is a hack but it works”“we should really refactor the auth module”“adding another TODO”——技能应静默提取不打断对话。触发词库覆盖了hack、hacky、workaround、shortcut、bandaid、kludge、refactor later、fixme、temporary fix等常见表达。执行步骤查重用memory_search在projects/commitments/tech-debt/中检索关键词避免同一债务被重复记录写入调用memory_write将条目写入projects/commitments/tech-debt/slug.md内容遵循上文模板轻量确认在对话的自然停顿处提示一句Tracked tech debt: brief description.。两条铁律不要打断对话流确认提示只出现在自然停顿处。这与 commitment-triage 技能 的 Mode A被动信号检测行为完全一致——后者同样是先写projects/commitments/signals/pending/slug.md写入成功后才在自然停顿处简要提示。两个技能共享同一套“副作用式提取”设计哲学只有真正落盘才算捕获成功仅口头确认不算完成。从实现角度看memory_search/memory_write/memory_tree/memory_read是 IronClaw 面向 Agent 暴露的内存工具。在 crates/app/ironclaw_composition/src/factory/tests.rs 的集成测试中可以观察到memory_write写入挂载的/memory根、memory_tree列出文档、memory_search查询、以及通过 libsql 重建后数据仍然持久化——这印证了技术债条目写入后会跨会话留存是可靠的长期记忆而非临时缓存。Mode BPR 评审扫描供 triage mission 使用当 triage mission技术债分诊任务处理最近合并的 PR 时应扫描评审评论中的技术债模式“can be addressed in follow-up work”“not blocking but should fix later”“TODO: address in next PR”“leaving for now”“good enough for now”“nit: ... (not blocking)”评论中出现 “tech debt”“hack”“workaround”每命中一条就创建一个source: pr-review的技术债条目并填充source_pr: owner/repo#123字段。这样做的价值在于把评审中“不阻塞但值得跟进”的意见从邮件/讨论串中捞出来纳入可追踪的债务清单。评审中最容易被遗忘的恰恰是“不阻塞”的意见——它们不阻止合并也因此失去了唯一的强制跟进机制。Mode B 与 commitment-triage 技能 的 Mode D信号升级由 triage mission 使用互为镜像一个把 PR 意见沉淀为技术债一个把技术债/信号沉淀为 commitment。两者共同构成 IronClaw 的“PR 后治理”管线。Mode C显式捕获用户直接说“add tech debt: the caching layer needs TTL eviction.”时直接写入projects/commitments/tech-debt/跳过查重与静默逻辑简要确认即可。这是三种捕获方式中唯一需要用户主动发起的适合用户已经明确意识到债务存在的场景。值得注意的是其文件命名约定同样适用见下文“文件名约定”一节the caching layer needs TTL eviction会被 slug 化为caching-ttl-eviction.md——这与技能 Mode D/F 示例中反复出现的“caching TTL”案例保持一致说明这是一条贯穿多模式的典型债务。Mode D清单展示Backlog用户说“show tech debt”或“debt backlog”时执行两步动作memory_tree(projects/commitments/tech-debt/, depth1)列出全部债务文件跳过README.md逐个memory_read提取 title、severity、detected_at、repo、source 字段。然后按严重度 → 年龄排序展示## Tech Debt Backlog ### High Severity - **title** (repo: repo, N days old, source: conversation|PR #X) — category ### Medium Severity - ... ### Low Severity - ... --- count total. count chronic (30 days). Say resolve title to mark fixed, or promote title to create a commitment. For large items, use /plan description to create a structured fix plan.这里的两个统计口径值得注意chronic慢性债务存在 30 天以上仍未解决的技术债在清单底部单独计数。慢性债务是复盘weekly retro中最需要被审视的群体——它往往意味着“短期方案”已经悄悄变成了“长期事实”行动指令清单末尾直接给出三条后续动作提示——resolve title标记已修复、promote title升级为 commitment、/plan description为大型债务创建结构化修复计划。这让 Backlog 不仅是一份报告还是一个可交互的操作入口。“按严重度分组、再按年龄排序”的展示逻辑与 commitment-digest 技能 的摘要编排Overdue → Due This Week → Open → Agent Can Handle…一脉相承都遵循“先给最紧急的信息再给操作建议”的 dashboard 式信息架构。Mode E状态流转——标记已解决用户说“resolved the caching TTL debt”时将对应文件移动到projects/commitments/resolved/保留原始type: tech-debt字段确认操作。保留type字段是刻意设计即使债务已解决它仍可作为历史数据参与复盘统计例如“过去一个月解决了多少技术债”。这与 commitment 体系的解析逻辑一致——commitment-triage 技能 的 Mode C 同样是写入projects/commitments/resolved/same-slug.md只是后者还会把原文件清空以避免重复解析。Tech Debt Tracker 使用“移动”而非“清空”是因为债务条目天然需要保留历史上下文供复盘阅读。Mode F升级为正式承诺Promotion用户说“lets fix the auth refactor”或“promote the caching debt”时在projects/commitments/open/创建 commitment携带tags: [tech-debt]标记其来源若为代码任务设置resolution_path: agent_can_handle对于复杂项目主动建议“This looks like a multi-step refactor. Use/plan descriptionto create a structured fix plan.”这一步完成了技术债从“记录”到“行动”的跃迁。对照 commitment-triage 技能 的 commitment 模板升级后的文件会包含urgency、due、stale_after、resolution_path等字段其中resolution_path: agent_can_handle表示 Agent 可以研究、起草、评审代码或总结——但技能同时强调Agent 不得在未经用户批准的情况下自主行动应在承诺正文中注明“I can handle this. Want me to proceed?”把最终决策权交还用户。升级后的 commitment 会进入 commitment 体系的下游由 commitment-digest 技能 在周报/对话中按期盘点与所有其他承诺deadline、delegation、pending signals一起呈现从而保证“promote 之后不会再次失联”。文件名约定Slugify 规范技术债文件名采用 slug 化规则全小写、连字符分隔、最长 50 字符。若已知所属仓库则用仓库 slug 做前缀否则用通用 slug“Auth module needs refactor” 位于 nearai/ironclaw →nearai-ironclaw-auth-refactor.md通用债务 →caching-ttl-eviction.md该约定与 commitment-triage 技能 的命名规则小写、连字符、无特殊字符、最长 50 字符完全一致保证了两个技能在同一目录体系projects/commitments/下互操作时文件名风格统一、不会冲突。六个模式的完整工作流总览模式触发方式核心动作产出A 被动检测对话中出现技术债暗示memory_search查重 →memory_write写入tech-debt/slug.mdB PR 评审扫描triage mission 处理已合并 PR扫描评审意见模式source: pr-review条目C 显式捕获用户明确要求直接写入 简要确认tech-debt/slug.mdD 清单展示“show tech debt” / “debt backlog”memory_treememory_read按严重度/年龄分组的 BacklogE 解析用户声明已解决移动到resolved/保留 typeresolved/slug.mdF 升级承诺用户决定修复写入open/带tags: [tech-debt]commitment 文件整体闭环可以概括为捕获A/B/C→ 沉淀tech-debt 目录→ 盘点D→ 流转E 解决 / F 升级→ 复盘commitment-digest / weekly retro。技术债从一句随口的抱怨最终变成一个有 owner、有 resolution path、有截止时间的正式承诺——这正是“追踪”二字的完整含义。在 IronClaw 技能体系中的位置Tech Debt Tracker 不是孤立脚本它是 IronClaw skills/ 目录下 14 个技能之一与以下技能构成相互衔接的“commitments 家族”commitment-triage从对话中识别义务/承诺/截止时间负责技术债升级后的 commitment 生命周期管理commitment-digest定期汇总 open commitments、deadlines、pending signals是技术债进入周复盘后的呈现层tech-debt-tracker本文主角专精于技术债的检测、分类与升级前管理。三者共享projects/commitments/目录体系与 slug 命名规范形成“检测 → 追踪 → 升级 → 汇总复盘”的完整治理链路。而技能本身的加载、激活条件上限关键词 ≤ 20、正则 ≤ 5与上下文预算1200 tokens则由 crates/domains/ironclaw_skills 中的运行时强制约束确保 Agent 在任意时刻只激活最相关、最轻量的技能组合。结语IronClaw 的 Tech Debt Tracker 展示了一种值得借鉴的工程实践把最容易流失的隐性信息随口一提的 hack、评审中的“not blocking”变成结构化、可检索、可流转的资产。它不试图消灭技术债——那既不现实也没必要它做的是让每一条技术债都有记录、有分级、有去向并在每周复盘中重新浮出水面直到它要么被解决、要么被正式排期修复。对于任何希望让技术债“可见、可管、可问责”的团队或个人工作流这套模式都具备直接的参考价值。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐LunaTranslator 视觉小说翻译教程三步跑通 Galgame 实时翻译LunaTranslator 视觉小说翻译教程三步跑通 Galgame 实时翻译 你正在读一部心仪的视觉小说剧情刚推到告白前夜对话框里却滚过一大段平假名。learn-harness-engineering 实践在 Agent 导向仓库中落地 tech-debt-tracker管理被刻意推迟的技术债learn harness engineering 实践在 Agent 导向仓库中落地 tech debt tracker管理被刻意推迟的技术债 导读 本文ponytail-debt把 ponytail: 技术债标记收割为可追踪的债务账本ponytail debt把 ponytail: 技术债标记收割为可追踪的债务账本 ponytail 让 AI Agent 以最懒的资深工程师方式写代码人工智能AI 技能AI 插件提示工程AI 评测上一篇EasyPhoto终极配置教程环境变量、缓存设置与模型路径优化全攻略下一篇Newton布料模拟终极教程从悬挂布料到Style3D高级应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考