codecontext
为AI编程助手提供代码关键上下文注释，防止误改
安装使用
复制下面这段提示词发给你的 AI（Claude / Cursor / TRAE / Codex / WorkBuddy 等），它会自动帮你完成安装：
帮我安装这个 AI Skill：codecontext。 它的用途是：为AI编程助手提供代码关键上下文注释，防止误改 完整的 Skill 内容见：https://321skill.com/skills/codecontext/raw/index.md 请读取该页面内容，如果是 SKILL.md 格式直接安装，如果是 README 提炼核心 prompt 后安装。
提示词包含完整的 Skill 内容链接，AI 读取后即可完成安装。你也可以 查看完整内容 确认无误。
使用示例
“请优化src/payments/gateway.ts文件中的时间戳判断逻辑。” AI在读取文件时，会先看到内联的`// @context decision ...`注释，了解到必须使用严格`>`而非`>=`的历史原因和关联技能文档，从而避免引入错误。工具链可在AI提交修改后运行`npx codecontext --diff`检查上下文是否仍然有效。
介绍
codecontext 解决的核心问题是：AI助手或工程师在修改代码时，因不了解代码背后非显而易见的约束、权衡和风险（这些信息通常埋没在历史提交记录或文档中）而引入错误。例如，一个看似可以“清理”的 > 操作符，背后可能隐藏着防止双重支付的业务逻辑，误改为 >= 可能导致严重事故。
该工具通过在代码行内嵌入结构化的TSDoc风格注释（如 // @context decision ...）来工作。这些注释将关键决策原因、验证日期和关联文档链接直接附加在代码旁。当AI或开发者编辑代码时，可以预先读取这些上下文；工具还能通过 --diff 命令检查编辑是否使上下文失效，强制要求重新验证，从而在变更落地前拦截风险。
它非常适合需要与AI编程助手（如Claude、Cursor）协作的团队，以及对代码历史决策传承有高要求的复杂项目维护者。它能确保“意图”在人员交接、AI迭代和代码评审中得以保留。
与传统的代码注释、测试或文档相比，codecontext 的核心区别在于其“机器可读性”和“主动性”。它不是被动的文档，而是能通过工具链被AI和自动化流程主动消费、验证的约束声明。它不替代测试，而是与测试互补：测试保护行为正确，codecontext 保护行为意图不被误读。
核心特点
核心区别在于将关键决策上下文以机器可读、可验证的格式直接内联在代码中，并设计了“新鲜度门禁”，当AI或开发者修改相关代码而未重新验证上下文时，工具能主动检测并阻止。这不同于仅靠代码注释或外部文档，后者容易被忽略且无法被工具链强制执行。
注意事项
不适合代码风格或简单逻辑等无需长期维护关键决策上下文的场景，过度使用可能增加代码视觉噪音。
常见问题
codecontext 和写普通注释有什么区别？
codecontext注释是结构化的、机器可读的，能被专用工具解析和验证，并能关联到外部文档（如技能文件），确保上下文在编辑时被主动消费，而普通注释容易被忽略。
用了这个还需要写单元测试吗？
需要。codecontext保护“意图”（为什么代码要这么写），测试保护“行为”（代码是否按预期工作），两者是互补关系，目的不同。
给 AI 助手的安装指引
如果你的 AI 编程助手（Claude Code、Cursor、TRAE 等）能看到这个页面，把下面这段发给它即可自动完成安装：
请访问 https://321skill.com/skills/codecontext/raw/index.md 读取 codecontext 的原始 Skill 定义（Markdown 格式），按其中说明在我的环境里完成安装和配置。
AI 可直接读取的原始 Markdown 地址：/skills/codecontext/raw/index.md（查看排版版本）