开发者推出新型 AI 文本检测工具，主打证据拆解与可解释性

前沿哨所

• Agent Skill 跨工具复用: 目录结构、版本管理与团队共享

  TL;DR: 多工具时代, skill 不该各管各的

  如果你同时在用 Claude Code、Codex、openclaw、hermes 这类 agent 工具, 大概率已经踩进同一个坑: 同一套”让 agent 怎么提交代码””怎么写 commit message””怎么发布到 WordPress”的知识, 被你在四个工具里各写了一遍。改一处, 另外三处忘了同步; 半年后想不起来哪个版本是最新的; 换台机器又得手动拷一遍。

  这不是工具的问题, 是你把 skill 当成了”每个工具的私有配置”, 而不是”独立于工具存在的工程资产”。

  一句话结论: agent skill 本质是纯文本 + 脚本目录, 天然适合用 git 管理、用软链或子模块在多工具间共享一份源、用语义化版本号追踪演进。 把这三件事做对, 你维护的就从”四份会漂移的副本”变成”一份可 diff、可回滚、可团队协作的真相源”。

  下面按这个顺序拆: 先讲清楚 skill 到底是什么、为什么能跨工具复用; 再给标准化目录结构; 然后是一份源多工具复用的几种接法; 接着是 git 版本管理与变更记录; 最后是跨工具迁移的差异点和团队协作流程。

  读之前如果你对 agent 工具本身还没选定, 可以先看 Claude Code vs Codex vs WorkBuddy vs Zcode: AI 编程 Agent 怎么选 和 Codex vs Cursor 额度对比: 价格、限制与选型建议, 把工具盘子定下来再谈复用更有意义。

  一、Agent Skill 的本质: 为什么它能跨工具

  1.1 Skill 不是插件, 是”可被加载的专业知识包”

  很多人第一次接触 skill, 会下意识把它类比成浏览器插件或者 IDE 扩展——一个绑死在某个宿主里、调一套私有 API 的二进制。这个类比会把你带偏。

  以 Claude Code 的 Skill 范式为例, 一个 skill 的核心就是一个文件夹, 里面放一份 SKILL.md。这份 markdown 顶部有 YAML frontmatter, 只需要两个字段就能跑起来:

  ---
  name: commit
  description: 用规范化的 conventional commit 信息创建提交。当用户要求提交代码、写 commit message、整理变更时触发。
  ---
  
  # Commit Skill
  
  ## 何时使用
  当工作区有未提交改动, 且用户要求"提交""commit""存一下"时。
  
  ## 步骤
  1. 运行 `git status` 和 `git diff` 看清改了什么
  2. 按 conventional commit 规范归类: feat / fix / docs / chore ...
  3. 生成简洁的标题 + 必要的正文
  4. 提交前用 `git diff --staged` 复核
  

  注意它的形态: 没有一行宿主专属代码, 全是自然语言 + shell 命令。 这正是它能跨工具的根本原因——它描述的是”做这件事的方法”, 而方法本身不依赖某个特定 agent 的运行时。

  1.2 渐进式加载: description 是检索入口, 不是装饰

  Claude Code 的 skill 有一个关键机制叫渐进式披露 (progressive disclosure): 系统启动时, 并不会把每个 skill 的全文塞进上下文, 而是只加载 name 和 description 两个字段。模型根据当前任务语义匹配到某个 description, 才会去读那份 SKILL.md 的正文; 正文里再引用 references/ 或 scripts/ 时, 又是按需加载。

  这套机制对”复用”有两个直接含义:

  • description 写得好不好, 决定了 skill 能不能被正确触发。 它不是文档摘要, 是检索关键词。要把”什么时候用我”写清楚, 把用户可能说的触发词都覆盖到。
  • 正文和资源按需加载, 意味着一个 skill 可以很厚而不污染上下文。 你可以把长 checklist、模板、参考表都塞进 references/, 平时不占 token, 用到才拉。

  这种”薄入口 + 厚实现”的思路, 和 agent 工程里反复出现的一个判断是同构的: 复杂度应该沉淀进可复用的资产, 而不是困在一次性对话里。关于 harness 和 skill 谁轻谁重的取舍, Agent Harness 不是要安装的软件包 和 Loop Engineering 是 Harness 的局部命名 讲得比较透, 值得对照着读。

  1.3 为什么”纯文本 + 脚本目录”是可迁移的最大公约数

  再看 Codex、openclaw、hermes。它们各自的扩展机制在字段名、加载方式上肯定有差异——Codex 有自己的指令文件与自定义提示约定; openclaw、hermes 这类工具有各自的组织方式。但把它们抽象一层就会发现, 几乎所有 agent 工具的”能力扩展”都落在同一个最大公约数上:

  一段告诉 agent 怎么做某件事的自然语言提示, 加上一组它可以调用的脚本/命令。

  以 hermes 这类偏调度型的 agent 为例, 它的 skill 通常也是走 prompt 描述 + 脚本目录的组织方式; openclaw 这类工具同理。字段叫什么、放在哪个目录、用什么格式声明触发条件, 这些是表层差异; 而”提示 + 脚本”这个内核是共享的。

  这就是跨工具复用在工程上成立的前提: 你维护的真相源应该是这个内核, 而把各工具的表层差异留给一层薄薄的适配。下面所有方法论都建立在这个判断上。

  二、标准化目录结构: 一份 skill 长什么样

  复用的第一步是约定结构。如果每个 skill 的内部布局都不一样, 后面的软链、迁移、版本管理都无从下手。下面是一套被验证可用的标准布局——它向 Claude Code 的 skill 约定看齐, 同时刻意保持”任何工具都能消费”的中立性:

  skills/
  ├── commit/
  │   ├── SKILL.md            # 入口: frontmatter(name/description) + 正文
  │   ├── references/         # 按需加载的厚资料: 规范表、模板、checklist
  │   │   └── conventional-commit-spec.md
  │   └── scripts/            # 可执行脚本, 被正文引用
  │       └── gen-message.sh
  ├── blog-publish/
  │   ├── SKILL.md
  │   ├── references/
  │   │   ├── seo-title-rules.md
  │   │   └── frontmatter-template.md
  │   ├── scripts/
  │   │   ├── build-images.py
  │   │   └── publish.sh
  │   └── assets/             # 静态资源: 模板图、样式片段
  │       └── poster-base.svg
  └── code-review/
      ├── SKILL.md
      └── references/
          └── review-checklist.md
  

  几条约定值得明确:

  1. 一个 skill 一个目录, 目录名即 skill 名, 和 frontmatter 里的 name 保持一致。这样工具扫描目录就能建立索引。
  2. SKILL.md 是唯一入口, 正文尽量短, 把”何时用 / 怎么用 / 边界”讲清楚即可。详细规则下沉到 references/。
  3. scripts/ 放确定性逻辑。 agent 擅长决策, 不擅长精确执行重复步骤。能用脚本固化的(改文件名、调 API、跑校验), 就别让模型每次现写。这点和”把 agent 当决策者、把确定性留给代码”的工程直觉一致, 构建 Agent 和写软件, 是两种工程 对这个边界有专门的讨论。
  4. references/ 是按需加载区。 越厚越好, 因为平时不占上下文。SEO 清单、品牌规范、API 字段表, 都该放这里。
  5. assets/ 放二进制或静态模板, 和会频繁 diff 的文本分开, 避免污染 git 历史。

  这套结构的好处是关注点分离: 决策(SKILL.md)、知识(references)、执行(scripts)、资源(assets)各居其位。换工具时, 你迁移的是整个目录, 而不是从一坨混在一起的配置里抠。

  三、一份 skill 源, 多工具复用

  结构定了, 接下来是核心问题: 同一个 skill, 怎么让 Claude Code、Codex、openclaw、hermes 都能用上, 而只维护一份源?

  核心原则只有一句: 真相源 (source of truth) 唯一, 各工具的目录是它的投影。 不要在每个工具的配置目录里各放一份会各自演化的副本。下面是三种接法, 从轻到重。

  3.1 方案 A: 软链接 (symlink)——最轻, 适合单人多工具

  把所有 skill 集中放在一个独立仓库, 比如 ~/agent-skills/。然后在每个工具期望的目录位置, 用软链指过去:

  # 真相源
  ~/agent-skills/skills/commit/
  ~/agent-skills/skills/blog-publish/
  
  # 各工具消费点, 全部软链到同一份源
  ln -s ~/agent-skills/skills  ~/.claude/skills
  ln -s ~/agent-skills/skills  ~/.codex/skills
  ln -s ~/agent-skills/skills  ~/.config/openclaw/skills
  

  改一处, 处处生效, 因为它们物理上就是同一份文件。优点是零同步成本、改完立即可见; 缺点是软链对某些工具的扫描器不一定友好(有的工具不跟随符号链接), 跨机器要重新建链, Windows 下软链权限也更麻烦。

  适用场景: 单人、同一台开发机、多个工具。这是收益最高、成本最低的起点。本站把自营分站统一管理时也用过类似”一份源 + 多处指向”的思路。

  3.2 方案 B: git submodule——适合多仓库、需要钉版本

  如果 skill 要被多个项目仓库引用, 而且你希望每个项目能钉在某个 skill 版本上(不被上游改动随时影响), 用 git submodule:

  # 在项目仓库里把 skill 仓库挂为子模块
  cd my-project
  git submodule add [email protected]:me/agent-skills.git .agent/skills
  
  # 各工具再软链到子模块目录, 或工具直接读这个路径
  ln -s ../.agent/skills .claude/skills
  
  # 升级时显式拉取并锁定到新 commit
  cd .agent/skills && git pull origin main && cd -
  git add .agent/skills && git commit -m "chore: bump skills to latest"
  

  submodule 的关键价值是版本锁定: 子模块在父仓库里记录的是一个确定的 commit hash。这意味着 A 项目可以用 skill 的 v1.2, B 项目还停在 v1.0, 互不干扰, 升级是一次显式的、可在 PR 里 review 的动作。代价是 submodule 的心智负担确实存在(忘记 --recurse-submodules、游离 HEAD 等老问题), 团队得统一约定。

  3.3 方案 C: 同步脚本——工具不认软链时的兜底

  有些工具就是不跟随软链, 或者要求 skill 必须是真实文件。这时用一个幂等的同步脚本, 把真相源拷贝到各工具目录:

  #!/usr/bin/env bash
  # sync-skills.sh —— 把真相源同步到各工具消费目录
  set -euo pipefail
  SRC="$HOME/agent-skills/skills"
  
  for dst in 
    "$HOME/.claude/skills" 
    "$HOME/.codex/skills" 
    "$HOME/.config/openclaw/skills"
  do
    mkdir -p "$dst"
    rsync -a --delete "$SRC/" "$dst/"   # --delete 保证目标和源一致, 不留孤儿
    echo "synced -> $dst"
  done
  

  rsync --delete 保证目标目录和源完全一致, 不会留下已删 skill 的残骸。把这个脚本挂到 git 的 post-merge hook 或一条手动命令上, 每次更新源后跑一次即可。它比软链笨, 但最通用——任何工具都吃真实文件。

  三种方案不互斥: 常用工具走软链, 个别挑食的工具用同步脚本补齐, 跨项目引用上 submodule。判断标准就一条——永远只有一份会被编辑的源, 其余都是它的只读投影。 这和”不要重复造轮子、把基础设施收敛成一份”的工程主张是一回事, 告别重复造轮子: 为什么 AI Agent 创业不应自研基础设施 把这个取舍讲到了创业层面。

  四、版本管理: 用 git 把 skill 当代码养

  skill 是纯文本, 这意味着它能享受软件工程几十年积累的全部版本管理红利。别浪费这个优势。

  4.1 skill 仓库本身就该是个 git 仓库

  最基本的一步: ~/agent-skills/ 初始化成 git 仓库, 推到远端。这样你立刻获得三件事——历史可追溯(谁在什么时候改了哪条规则)、可回滚(某次改动让 skill 触发变差, 一个 git revert 回去)、可 diff(改动一目了然, 因为全是文本)。

  这正是”纯文本 + git”组合的核心价值。对比一下: 如果你的 skill 是埋在某个工具 GUI 里的配置项, 上面这三件事一件都做不到。

  4.2 语义化版本: 给 skill 打 tag

  当 skill 开始被多个项目、多个人引用时, 引入语义化版本 (SemVer) 就有意义了。约定:

  • MAJOR (2.0.0): 破坏性变更。比如改了 skill 的触发语义、删了某个被脚本依赖的字段、调整了输出格式, 老的调用方需要适配。
  • MINOR (1.3.0): 向后兼容地加能力。新增一个 reference、扩展触发词、加一个可选脚本。
  • PATCH (1.2.1): 修字。typo、措辞优化、修一个脚本 bug, 不改行为契约。

  打 tag 的操作:

  git tag -a v1.3.0 -m "blog-publish: 新增 SEO 标题硬规则 reference"
  git push origin v1.3.0
  

  submodule 引用时, 就可以钉到 v1.3.0 这个 tag 而非游动的 main, 升级变成”从 v1.3.0 到 v1.4.0″这种可读、可评审的动作。

  4.3 CHANGELOG: 让”为什么这么改”留痕

  git 历史记录了”改了什么”, 但”为什么改、改了之后触发效果有没有变好”需要单独留痕。在 skill 仓库根放一份 CHANGELOG.md:

  # Changelog
  
  ## [1.3.0] - 2026-06-26
  ### Added
  - blog-publish: 接入 SEO 标题硬规则 reference, 标题生成前强制过清单
  ### Changed
  - commit: description 补充"存一下""归档"等触发词, 提升命中率
  
  ## [1.2.1] - 2026-06-20
  ### Fixed
  - code-review: 修正 checklist 里一处误导性表述
  

  这件事在 agent 语境下尤其重要。skill 的好坏不像普通代码那样有确定的单元测试, 它的”对不对”体现在触发是否准、产出是否稳。 你改一版 description, 触发率可能上去也可能下去, 这本质是个需要观测的反馈过程。把每次改动和它的意图记下来, 才能在效果回退时定位是哪一次改坏的。

  关于”agent 的效果如何度量”这件事本身就是门学问, LLM 评测的下一步是一张二维矩阵 和 Prompt Learning 的两个反馈圈 提供了两套可以直接借用的视角: 前者讲怎么把评测组织成可读的矩阵, 后者讲提示迭代的反馈闭环, 都能套到”skill 改完怎么验证”上。

  五、跨工具迁移: 差异点在哪里, 怎么处理

  把内核标准化之后, 真正的工作量在处理各工具的表层差异。这里列出迁移时最常踩的几类差异和应对。

  5.1 frontmatter / 元数据格式差异

  不同工具对”这个 skill 叫什么、什么时候触发”的声明方式不一定相同。Claude Code 用 SKILL.md 顶部的 YAML frontmatter(name + description); 其他工具可能用别的文件名、别的字段、甚至别的格式。

  应对: 真相源用一套最表达力强的格式(推荐 Claude Code 的 frontmatter 约定), 迁移时用一个小转换脚本生成各工具要的形态。 不要反过来——不要为了迁就某个工具的弱格式, 把真相源也阉割了。

  5.2 触发机制差异: 自动检索 vs 显式调用

  这是最容易出问题的一类差异。有的工具像 Claude Code 那样靠 description 语义自动匹配触发 skill; 有的工具需要用户显式调用(比如打一个斜杠命令)。

  这两种机制对 description 的要求完全不同:
  – 自动匹配的工具, description 要写得像”检索关键词”, 把所有可能的触发说法都覆盖。
  – 显式调用的工具, description 更像”帮助文档”, 用户已经知道要调它了。

  应对: 把 description 写成自动匹配友好的版本(信息量大的那种总是兼容显式调用), 在迁移到显式调用工具时不需要改。反过来则会丢信息。

  5.3 脚本运行环境差异

  scripts/ 里的脚本依赖的解释器、环境变量、工作目录, 在不同工具下不一定一致。一个在 Claude Code 下 cwd 在项目根的脚本, 换个工具可能 cwd 在别处。

  应对三原则:
  – 脚本内部一律用绝对路径或相对脚本自身定位, 不假设 cwd。
  – 依赖通过环境变量注入, 不硬编码。尤其涉及密钥时, 走 bootstrap 读取, 绝不写死在脚本里。
  – 跨工具差异用一层适配 wrapper 吸收, 别让核心脚本里长出 if 工具==X 的分支。三个以上分支就是设计出问题的信号。

  跨模型/跨 SDK 调用时还有一类隐蔽差异是错误格式不统一, 同一个失败在不同链路下报得五花八门, AI_ProviderSpecificError 报错定位与修复: AI SDK 排错 是一个具体的踩坑样本, 迁移脚本前扫一眼能省时间。

  5.4 能力边界差异

  不是每个工具都给 skill 同等的权限。有的能跑任意 shell, 有的沙箱限制严格; 有的能联网, 有的不行。一个重度依赖 shell 的 skill 迁到受限工具里可能直接哑火。

  应对: 在 SKILL.md 里显式声明这个 skill 的依赖前提(需要 shell、需要网络、需要某个 CLI 已安装)。迁移时先核对目标工具是否满足, 不满足就降级或标记为不可用, 而不是让它在运行时静默失败。

  六、团队共享: 从个人资产到协作流程

  单人复用解决”我自己别重复劳动”; 团队共享要解决”全队用同一套规范, 且改动可控”。

  6.1 集中仓库 + PR 流程

  把 skill 仓库放团队可访问的 git 远端, 任何人改 skill 都走 branch + PR + review。这件事的价值在于: skill 是会直接影响 agent 行为的”准代码”, 一个人随手改了 commit skill 的规范, 全队的提交风格就变了。让它走 review, 和 review 代码同等对待。

  git checkout -b feat/blog-skill-seo-rules
  # 改 skills/blog-publish/references/seo-title-rules.md
  git add . && git commit -m "feat(blog-publish): 加入 SEO 标题硬规则"
  git push origin feat/blog-skill-seo-rules
  # 开 PR, 团队 review 触发效果与措辞后合并
  

  6.2 安全审查: skill 也是攻击面

  这一点必须单独强调。skill 里有 scripts/, 有命令, 有时还有凭据读取逻辑。一个被污染的 skill, 等于让 agent 在你机器上跑了一段你没仔细看的脚本。 团队共享放大了这个风险——一个人引入恶意或粗心的 skill, 影响全队。

  所以 skill 仓库的安全要求不能靠”感觉没问题”:
  – 脚本不硬编码密钥, 走 bootstrap / 环境变量。
  – review 时重点看 scripts/ 里有没有外发数据、有没有读敏感文件、有没有往临时目录写可执行文件。
  – 来源不明的第三方 skill, 先在隔离环境跑过再进主仓。

  “安全要的是证明而不是感觉”这个判断对 skill 同样成立, 安全不是氛围, 是证明 讲的虽然是 prompt 安全, 但”不能靠语义过滤器兜底, 要靠可验证的约束”这个内核, 直接适用于 skill 脚本审查。

  6.3 文档即接口: README + 触发词索引

  团队规模上来后, 别人不知道你这有哪些 skill、什么时候该用哪个。在仓库根维护一份索引, 列出每个 skill 的 name、description 摘要、依赖前提、维护人。这本质是把”文档即接口”落到实处: 一份能驱动别人正确调用 skill 的索引, 才算把这套资产建模完整了。

  6.4 复用的边界: 不是所有东西都该做成共享 skill

  最后一条反向提醒: 不要把什么都做成团队级 skill。高度个人化的工作习惯、一次性的探索脚本, 留在个人层就好。团队仓库里只放真正需要全队一致的东西(提交规范、发布流程、安全 checklist)。skill 太多太杂, 反而增加 description 之间的语义干扰, 让自动触发的工具选错。关于”什么该沉淀、什么该丢”, 选型层面的 AI Agent 框架全景: LangChain/LangGraph/n8n/Dify 等选型指南 给了一个可类比的取舍框架: 先定决策维度, 再决定收口到哪一层。

  七、相关阅读

  把这套方法论放进更大的 agent 工程图景里, 下面几篇可以接着读:

  • Claude Code vs Codex vs WorkBuddy vs Zcode: AI 编程 Agent 怎么选 —— 先把工具盘子定下来。
  • Agent Harness 不是要安装的软件包 —— harness 与 skill 的边界划分。
  • 构建 Agent 和写软件, 是两种工程 —— 为什么 skill 要把决策和确定性执行分开。
  • 把 Agent 送上生产: RAG、工程、安全、评测 —— skill 只是生产化拼图的一块。
  • 开源 AI Agent 调试器 HALO: 利用 RLM 技术实现本地化闭环优化 —— skill 改完后怎么观测闭环效果。
  • AI 信源指南: 收录 Karpathy、Sam Altman 等百余位顶级专家的 X 平台关注清单 —— 跟进 agent 工具演进的信息源。

  如果你是从零搭 agent 开发能力, 技术社区热议: AI Agent 开发的学习路径与资源盘点 适合作为更靠前的入门索引。

  八、FAQ

  Q1: skill 用 markdown 写, 不会因为太”软”而不可靠吗?

  可靠性不来自格式的”硬”, 来自结构和验证。把确定性逻辑沉到 scripts/(那部分是真代码, 可测), 把决策留给 SKILL.md(那部分本来就该是自然语言)。再配上 git 历史和 CHANGELOG, 你对每次改动的效果有迹可循。这比埋在 GUI 里、改了无从追溯的”硬配置”可靠得多。

  Q2: 我只用一个工具, 还有必要搞这套吗?

  值得做的是其中两件: git 版本化和标准化目录。这两件即使单工具、单人也立刻回本——你获得了回滚能力和清晰结构。软链/子模块/同步脚本那部分是多工具才需要的, 单工具可以先不碰, 等你哪天加第二个工具时再补, 成本也不高。

  Q3: openclaw、hermes 这类工具的 skill 格式和 Claude Code 不一样, 怎么共享?

  共享的是内核(提示 + 脚本目录), 不是表层格式。真相源用表达力最强的格式(推荐 Claude Code 的 frontmatter 约定)写一份, 各工具的具体格式用一层转换/适配脚本生成。具体差异在哪、怎么吸收, 见第五节”跨工具迁移”。核心是: 永远不要为了迁就某个工具的弱格式去阉割真相源。

  Q4: 软链、子模块、同步脚本, 到底用哪个?

  按场景: 单人单机多工具用软链(最轻); 跨项目引用、要钉版本用子模块(可锁 commit); 工具不认软链时用同步脚本(最通用)。三者可以混用, 唯一的铁律是——只有一份会被编辑的源, 其余都是只读投影。

  Q5: 团队里怎么防止有人引入有问题的 skill?

  把 skill 仓库当代码仓库管: 改动走 PR + review, 重点审 scripts/ 里的命令(有没有外发数据、读敏感文件、写可执行文件到临时目录), 密钥一律走 bootstrap 不硬编码, 第三方来源先隔离环境跑过再进主仓。详见第六节 6.2。

  九、结语

  agent 工具会一直增加, 这是确定趋势。如果你的 skill 跟着工具走, 每多一个工具就多一份要手动同步的副本, 维护成本是线性甚至超线性增长的。

  换个建模方式: 把 skill 当成独立于工具存在的工程资产——纯文本、可 diff、git 版本化、一份源多处投影。这样每多一个工具, 增加的只是一条软链或一段适配, 边际成本趋近于零。

  落地就三步, 今天就能起: 第一, 把散在各工具里的 skill 收进一个 git 仓库, 按标准目录结构摆好; 第二, 选软链或同步脚本, 让各工具指向这一份源; 第三, 给重要 skill 打上 tag、补上 CHANGELOG。从”四份会漂移的副本”到”一份可维护、可审计、可共享的真相源”, 差的不是工具, 是把它当资产来养的这套习惯。

  6小时前

• 提升 AI 编程效率：开发者推出冷启动工具 Harness Kit，构建智能体规范化开发环境

  一位开发者日前在技术社区 Linux.do 发布了开源项目 “harness-kit”，旨在为 AI 编程环境提供冷启动解决方案。该项目作者提出了 “Harness” 的概念，将其视为构建高质量 AI Agent 开发循环的前提环境。作者分享的工程实践涵盖了完整的开发流程闭环：在开发前，利用工程提示词引导智能体进行 TDD（测试驱动开发），在功能完成后编写冒烟或端到端测试，并通过 Git hooks 在提交前建立质量门禁；在知识库方面，结合 OpenViking、GitNexus 等工具为 AI 提供上下文支持；在开发过程中，采用 SDD（规范驱动开发）结合自定义的 repo-guard 机器人进行自动化代码审查。通过构建这一 “Harness” 环境，开发者可以在 Cursor 或 GitHub Copilot 等 AI 编码工具中，通过简单的指令（如 /goal 或 /loop）驱动智能体完成从 Issue 创建、代码开发、提交到代码审查的自动化流程。harness-kit 作为一个 CLI 工具，旨在帮助开发者快速在仓库中搭建上述包含测试、知识库和审查机制的规范化环境，降低 AI 辅助编程的配置门槛，从而提升开源项目的开发质量与效率。

  事件分析

  从技术架构角度看，该事件反映了 AI 编程从单纯的对话式辅助向自动化、规范化工程流演进的趋势。当前，AI 智能体在处理长程任务时容易因缺乏上下文或约束而偏离目标，harness-kit 实际上是在尝试构建一套 “护栏” 机制。通过引入 TDD、自动化测试门禁、代码审查机器人等传统软件工程要素，该工具将 AI 的编码行为封装在既定的质量框架内，解决了 “Vibe Coding”（氛围式编程）可能带来的代码质量不可控问题。这表明，未来的 AI 开发工具竞争焦点将不仅是生成代码的能力，更是管理开发流程、维护代码规范以及集成知识库的整合能力。此类冷启动工具的出现，降低了个人开发者构建 AI 工程化流水线的难度，有助于推动 AI 辅助开发在严肃生产环境中的落地。

  💡 核心观点：AI 编程正从单点生成转向全流程工程化，构建包含测试与规范的 “Harness” 环境是释放智能体潜力的关键。

  原文链接：Linux.do

  10小时前

• 从“模型坍塌”到“人类退化”：开发者反思 AI 对创造力的侵蚀

  近日，一位开发者在技术社区 V2EX 发文，表达了在整理旧时代 Git 仓库时对当前技术环境的反思。该开发者通过对比过去充满“青涩文笔”和“大开脑洞”的原创内容，与如今遇到任务首先寻求 AI 生成或润色的习惯，指出了 AI 依赖带来的认知惰性。文章引入了人工智能领域的“模型坍塌”（Model Collapse）概念作为核心隐喻，即 AI 模型若仅使用自身生成的合成数据进行再训练，会导致智力不可逆地退化。作者进一步提出了一个令人深思的假设：当人类越来越习惯于消费 AI 生成的内容，甚至让 AI 替代思考时，人类自身的智力水平是否会像模型一样遭遇“污染”和下降？尽管该开发者承认已无法脱离 AI 工具生活，但这一观点揭示了在 AI 生成内容（AIGC）泛滥的背景下，原创思维能力的萎缩风险，特别是对于出生在 AI 时代的“原住民”而言，如何在享受工具便利的同时保持大脑的独立运转与创造力，已成为一个不容忽视的社会性技术议题。

  事件分析

  此事件反映了技术社区对生成式 AI 深度介入创造性工作后的副作用进行的一次元思考。从技术原理上讲，这对应了机器学习中关于数据分布偏移与“模型坍塌”的讨论：当训练数据被合成数据污染，模型对长尾分布和真实复杂逻辑的理解能力会大幅衰减。映射到人类认知层面，若开发者将核心的架构设计与逻辑推演完全外包给 AI 编程工具，大脑神经网络因缺乏高强度、试错性的深度思考训练，可能导致逻辑构建能力的生理性退化。此外，如果互联网未来的内容增量主要由 AI 生成并回流给人类学习，这种闭环的“回音室效应”不仅限制了人类的视野上限，更可能导致未来数据集源头枯竭，即缺乏高质量的人类真实反馈数据，进而反向制约下一代大模型的演进潜力。

  💡 核心观点：当人类思维习惯退化为对 AI 产出的二次校对，创造力与逻辑能力的“模型坍塌”或许将成为技术进步的隐性代价。

  原文链接：V2EX 分享发现

  10小时前

• AI编程实战：非开发人员利用 Claude 耗时 10 天开发出首个 macOS 应用

  一位没有编程背景的设计师在 V2EX 分享了其利用 AI 技术耗时 10 天开发人生中第一款 macOS 应用的经历。该开发者受 PopClip 启发，希望拥有一款支持纵向模式和图标模式的工具，因此在 Claude 和 Codex 的辅助下完成了这一项目。开发过程分为三个核心步骤：首先是需求整理，通过草图和文档明确功能与界面布局，并咨询技术专家确认可行性；其次是版本构建，强调需向 AI 清晰描述核心需求以防止其随意更改逻辑，特别是在实现 Look Up 功能时需避免 AI 滥用默认方案；最后是打包测试，利用 GIF 录制 Bug 并喂给 AI 进行修复，期间还借助了 OpenPUA 等开源项目辅助。目前该应用已在 macOS 27.0 Beta 环境下打包测试，支持 macOS 13.0 及以上版本，开发者表示未来考虑加入 AI 结合功能后开源。这一案例生动展示了 Claude 等大模型在赋能非技术人员进行软件开发方面的显著潜力。

  事件分析

  此事件是“AI编程”从概念走向实用化的典型案例，标志着软件开发门槛正在经历结构性降低。Claude 等大模型在代码生成与逻辑理解上的表现，已足以支撑非技术人员完成包含 UI 布局、交互逻辑及本地功能调用的原生 macOS 应用开发。技术层面上，该案例突出了“提示词工程”与“视觉反馈”在 AI 辅助开发中的重要性，通过 GIF 录制问题并喂给模型修复的方式，有效解决了文本描述偏差导致的理解瓶颈。产业层面，这预示着软件开发职能的模糊化，设计师与产品经理正逐渐具备独立交付软件产品的能力，未来的工具链将更加侧重于自然语言交互与多模态反馈，而非传统的语法记忆。这有助于推动“公民开发者”群体在桌面端应用领域的爆发，加速软件创意的落地速度。

  💡 核心观点：Claude 等大模型正在将软件开发从“手艺活”转化为“逻辑描述”，设计师等非技术人员正成为新的应用创造者。

  原文链接：V2EX 分享发现

  10小时前

• 1M 上下文已经可用: Claude、Gemini 与编程 Agent 怎么选

  有人在搜索框里反复打”1m 上下文已经全量可用”。这背后不是想读一篇科普，而是一个很具体的工程疑问：我现在用的模型，到底是不是已经能吃下 100 万 token 的上下文？如果能，我该不该把整个仓库、整本手册、整批日志一股脑塞进去？

  先把结论给你：1M（100 万 token）上下文确实已经在主流前沿模型上”可用”，但”可用”不等于”该这么用”。 它真正改变的不是某个跑分，而是一类原本做不到的任务现在能一次性做完了——比如让一个 Agent 同时看懂跨十几个文件的调用链。代价同样真实：费用随 token 几乎线性上涨、首字延迟变长、还有一个工程师最容易踩的坑——长上下文衰减（模型在超长上下文里”中间遗忘”、检索质量下降）。

  这篇从工程师视角，把 1M 上下文在 Claude、Gemini、编程 Agent 三条线的可用性、成本和适用场景一次盘清楚。

  一、TL;DR：1M 上下文到底意味着什么

  100 万 token 大概是多少

  token 不等于字。粗略地说，1M token 对应的量级是：几十万到上百万字的中文文本，或者一个中等规模代码仓库的绝大部分源码，或者几百页 PDF 的全文。换句话说，你第一次可以把”整本书 / 整个项目”作为一个整体喂给模型，而不是切片喂。

  这就是它的核心价值：从”分块处理 + 人工拼接”变成”一次性全局理解”。在它之前，处理长文档要靠分段摘要、向量检索、滑动窗口这些工程手段绕；现在某些任务可以直接绕过这些中间层。

  一句话工程判断

  • 能用：截至目前，几家头部模型（Claude、Gemini 的部分版本）都提供了接近或达到 1M token 的上下文窗口，部分以 beta / 特定方案的形式开放。
  • 别滥用：窗口大小是”上限”，不是”建议值”。把 100 万 token 全填满，意味着每次请求都在为可能用不到的内容付费，同时把模型推向它检索能力最弱的区间。
  • 真正的工程问题：不是”能塞多少”，而是”该塞哪些、怎么组织、什么时候换成检索”。

  如果你正在为”用哪个模型 / Agent”纠结，可以先看这两篇横评打底：Claude Code vs Codex vs WorkBuddy vs Zcode: AI 编程 Agent 怎么选 和 GLM-5.2 vs GPT-5.5: 架构、Agent 与部署取舍对比，里面对各家的定位有更细的拆解。

  二、各家可用性盘点（定性，不报精确数字）

  先声明：各家官方上限、单价、beta 政策一直在变，下面只做定性取舍，不把精确数值当权威事实，确切数字请以你下单时的控制台为准。

  Claude：长上下文检索质量是强项

  Claude 这条线最被工程师认可的，是它在长上下文里的指令遵循和检索稳定性——把关键信息埋在很长的上下文中段，它相对不容易”漏读”。它的 1M 级窗口目前更多以特定层级 / beta 通道开放，定位偏向”需要一次性吃下大量代码或文档、且对准确度敏感”的场景。

  实际体感上，很多人是冲着 Claude Code 的工程闭环来的。关于它和 Codex 的对比体验，开发者实测：Claude Code 效率超越 Codex，AI编程迈向”零门槛”自然交互 和 遭遇GPT降智后转向Claude：开发者实测MCP协议打造”自举”式开发闭环 都有第一手记录。

  Gemini：超长窗口铺得最早、最广

  Gemini 系列是较早把”百万级上下文”作为主打卖点推开的，部分版本对外宣称的上限甚至更高。它的优势在于长文档、长视频、多模态混合的大批量摄入——一次塞进海量原始资料，让模型自己提取结构化信息。社区里有个很典型的用法：HN热帖：利用 Gemini 提取数据，绘制 Mini PC 性价比”帕累托前沿”，本质就是把成千上万条杂乱规格喂进大窗口做一次性归纳。

  编程 Agent / Codex：窗口大小≠Agent 好用

  这一层最容易被误解。编程 Agent 的实际”可用上下文”，往往不等于底层模型的窗口上限。 Codex、Cursor、Claude Code 这类工具会在你和模型之间做一层上下文管理：它们不会傻乎乎把整库代码塞满窗口，而是按需读文件、做摘要、压缩历史。

  所以横向选 Agent 时，窗口大小只是其中一个变量，更关键的是它的上下文调度策略、额度和稳定性。这几篇可以连起来看：Codex vs Cursor 额度对比: 价格、限制与选型建议、深度解析 Cursor Composer 2.5：从”套壳”争议到拥有工作流数据的巨头护城河，以及 开发者吐槽Claude Code配置混乱：pi的模块化管理被指更胜一筹——最后这篇讨论的”配置/上下文怎么模块化管理”，恰恰是大窗口时代的核心工程问题。

  定性对比一张表

  维度	Claude	Gemini	编程 Agent（Codex/Cursor/Claude Code）
  长上下文检索稳定性	强项，中段不易漏读	容量大，超长时检索质量需实测	取决于其上下文调度，而非底层窗口
  超大窗口铺开程度	特定层级 / beta	较早、较广，部分版本上限更高	不直接暴露满窗，按需读取
  最适合的活	准确度敏感的大代码/长文档	海量原始资料一次性归纳、多模态	多文件改动、跨文件调用链理解
  工程师该看的关键指标	检索准确率 + 价格	容量 + 衰减表现	上下文管理策略 + 额度 + 稳定性

  注：表中均为定性判断。涉及具体跑分时，社区/公开讨论里说法不一，请按你自己的真实任务做小样本实测，不要照搬别人的 benchmark 结论。

  三、真实成本与”长上下文衰减”陷阱

  这一节是全文重点，也是”1m 已经可用”这条搜索词背后最该被回答的部分——因为很多人以为可用就等于免费午餐。

  成本：token 几乎是线性涨的

  绝大多数 API 按输入 + 输出 token 计费。这意味着：你往上下文里多塞一倍内容，输入成本大致就翻一倍。 把窗口从几万 token 拉到接近 1M，单次请求成本可能是几十倍的差距。如果这是一个高频调用的 Agent 循环，账单会非常吓人。

  关于成本如何反过来决定架构选型，LLM时代的软件生存法则：SaaS自建与购买的成本临界点分析 把成本临界点量化得很清楚；订阅额度层面的真实痛点可以看 开发者热议AI订阅痛点：对比GPT Pro与Claude的额度与安全性。如果你在用中转 / 聚合方案压成本，AnyRouter 实测：模型路由、API 兼容与价格稳定性 也值得参考。

  延迟：窗口越满，首字越慢

  上下文越长，模型预填充（prefill）要处理的 token 越多，首字延迟会明显上升。对交互式编程 Agent 来说，每次都灌满窗口，体感就是”问一句要等很久”，开发循环被拖垮。

  缓解手段是 prompt caching（提示缓存）：把不变的大块前缀（如系统提示、整库代码）缓存住，后续请求复用，既省钱又省延迟。这是用好大窗口的关键工程技巧——不是少塞，而是让重复部分不重复计费。

  衰减：lost in the middle，长上下文的”中间遗忘”

  这是最隐蔽的坑。研究和大量实践都观察到一个现象：当关键信息位于超长上下文的中间位置时，模型的检索准确率会下降，业内常称为 “lost in the middle”（中间遗忘）。也就是说，你把 100 万 token 填满，模型未必真的”看清”了每一个角落——开头和结尾它记得牢，中段容易糊。

  这带来一个反直觉的结论：有时候塞得更多，效果反而更差。 因为你引入了大量噪声，稀释了真正相关的信号，还把关键内容推到了模型最不擅长的检索区间。

  举个具体的例子。假设你要让模型基于一份内部规范回答问题，规范一共三十页。做法一：把三十页全文连同其它二十份无关文档一起塞进窗口，凑到几十万 token；做法二：只把这三十页规范放进去，其它不放。直觉上做法一”信息更全”，但实际上做法一往往更差——真正相关的三十页被淹没在无关内容里，又恰好落在容易被忽略的中段，模型抓不住重点；而做法二上下文干净、相关密度高，答得反而更准、更便宜、也更快。这就是”精确投喂”为什么经常打败”应塞尽塞”。同样的道理放到代码上也成立：与其把整个 monorepo 灌进去，不如先定位到真正相关的那几个模块再交给模型。

  经验法则（按你的任务实测校准，不是绝对值）：
    上下文长度 ↑  →  单次成本 ↑（近线性）
                  →  首字延迟 ↑
                  →  中段检索准确率 ↓（lost in the middle）
  
  结论：上下文是有成本的资源，要"精确投喂"，不是"能塞就塞"。
  

  本地小模型在这点上更敏感——窗口、量化精度、显存三者互相挤压。想看这层取舍，Qwen3.6 27B vs Step3.7 IQ4_XS: 本地大模型量化精度实测 给了一张很实在的选型矩阵。

  四、什么场景该用大窗口、什么场景用 RAG 更划算

  把上面的成本和衰减放在一起，决策其实就清晰了：大窗口和 RAG（检索增强）不是二选一的对立，而是按任务形态分工。

  适合直接用大窗口

  • 需要全局连贯理解：跨多文件的代码重构、读懂一份逻辑环环相扣的长合同、分析一份首尾呼应的研究报告。这类任务一旦切片就丢失全局关系，大窗口是刚需。
  • 一次性、低频的大批量摄入：把一整批原始资料喂进去做一次归纳总结，跑完就走，不进入高频循环。
  • 多文件 Agent 任务：让 Agent 同时持有十几个相关文件，理解它们之间的调用关系再动手改。十年代码荒后的技术重构：创业老兵实测 Claude 与国产模型的多 Agent 协同差异 就是这种”多文件 + 多 Agent 协同”的实战样本。

  适合用 RAG / 检索

  • 海量、低相关密度的知识库：你有几百万字文档，但每次查询只用到其中很小一部分。把全部塞进窗口，等于为 99% 用不到的内容付费，还触发中间遗忘。这时候先检索召回相关片段、再喂给模型才是对的。
  • 高频、对成本敏感的循环：客服、问答这类每天上万次调用的场景，必须把每次请求的 token 压到最小。
  • 需要可溯源、可更新的事实：RAG 能给出引用来源，知识更新只要更新检索库，不用重灌上下文。

  决策表

  你的情况	优先方案	理由
  单次任务，内容强相关、需全局理解	大窗口	切片会丢关系，一次性看完最准
  知识库巨大，单次只用一小部分	RAG 检索	省钱、避开中间遗忘
  高频调用、成本敏感	RAG + 缓存	token 压到最小才扛得住账单
  多文件代码改动、跨文件依赖	大窗口（Agent 调度）	Agent 按需读取，兼顾全局与成本
  需要引用来源、知识常更新	RAG	可溯源、可增量更新

  实务里最常见的其实是混合：用 RAG 把候选范围缩到几万 token，再交给具备大窗口的模型做精读和综合。两边的长处都要。

  五、对编程 Agent / Claude Code / Codex 的影响

  对写代码的人来说，1M 上下文最大的意义不是”能读完整库”，而是改变了 Agent 维持项目记忆的方式。

  整库理解成为可能，但 Agent 仍在做减法

  理论上大窗口能让 Agent 一次看懂整个仓库。但前面说过，真把整库塞满既贵又触发衰减。所以成熟的编程 Agent 走的是“大窗口能力 + 智能上下文管理”的组合：底层有大窗口托底，上层仍然按需读文件、做摘要、压缩历史对话。窗口大小给了它”必要时能展开”的余地，而不是”每次都展开”的负担。

  上下文管理 = 长项目的真正分水岭

  长项目里，模型每次重新打开仓库都要”恢复现场”。从哪里恢复、恢复多少，决定了它还认不认得这套代码。Claude Code 长项目踩坑: vibe coding 与 spec coding 何时切换 把这个问题讲透了：原型阶段可以”想到哪写到哪”，但项目一长，必须靠规格（spec）和结构化的上下文来锚定，光靠塞大窗口救不回来。

  配置和上下文怎么模块化组织，也直接影响 Agent 的可维护性——开发者吐槽Claude Code配置混乱：pi的模块化管理被指更胜一筹 讨论的就是这件事。而当 Agent 的会话状态丢失时会有多痛，Codex CLI MCP 服务器 logout 吞 session: 复现与修复 是一个具体到根因的案例。

  多 Agent 协同会放大上下文成本

  当你从单 Agent 走向多 Agent，每个 Agent 都持有自己的上下文，总 token 消耗是叠加的。企业实战案例：多Agent系统重构人力资源招聘流程 能看到：Agent 越多、文档越复杂，上下文管理越是成败关键。任务对齐和拆解做得好，才不会让每个 Agent 都去灌满窗口，清华博士开源 COMPASS 司南生态更新：Task-Clarifier 升级，强化 Agent 任务对齐能力 走的就是这个方向。

  给工程师的落地建议

  # 用大窗口前，先问自己三个问题：
  # 1. 这些内容真的都"强相关"吗？还是能先检索缩范围？
  # 2. 这是单次任务，还是会进高频循环？（循环就别灌满）
  # 3. 不变的大前缀，有没有用上 prompt caching 复用？
  
  # 实操顺序建议：
  #   RAG 召回  →  组织成最小必要上下文  →  缓存稳定前缀  →  交给大窗口模型精读
  

  六、相关阅读

  • Claude Code vs Codex vs WorkBuddy vs Zcode: AI 编程 Agent 怎么选：选 Agent 的横评底盘，窗口只是其中一维。
  • GLM-5.2 vs GPT-5.5: 架构、Agent 与部署取舍对比：架构层面的取舍，理解各家定位差异。
  • 豆包 AI 优缺点实测: 对比 ChatGPT、Claude 与 Kimi：同一批任务横评四家，看长文本处理差异。
  • LLM时代的软件生存法则：SaaS自建与购买的成本临界点分析：成本临界点量化，决定你该不该上大窗口。
  • Codex macOS code_sign_clone 占几十 GB 磁盘: 真相与清理：用 Codex 时另一个容易被忽略的工程坑。

  七、FAQ

  Q1：1M 上下文现在是不是所有人都能用上？
  要分清”模型支持”和”你的账号 / 套餐能用”。前沿模型在技术上已经提供接近或达到 1M 的窗口，但是否对你开放，取决于你用的版本、层级、是否在 beta 名单内。最稳妥的办法是去你下单的控制台看当前上限，别照搬别人的截图。

  Q2：把整个项目塞进 1M 窗口，模型就能完全读懂吗？
  不能想当然。受 “lost in the middle”（中间遗忘）影响，塞得越满，中段信息越容易被忽略。整库代码更推荐交给具备上下文调度的编程 Agent，由它按需读取，而不是你手动一次性灌满。

  Q3：大窗口和 RAG 到底选哪个？
  看任务。内容强相关、需全局理解、单次低频 → 大窗口；知识库巨大但单次只用一小部分、高频、成本敏感 → RAG。现实里最常见的是两者混合：先检索缩范围，再用大窗口精读。

  Q4：用 1M 上下文会不会很贵？
  会。token 近似线性计费，灌满窗口的单次成本可能是常规请求的几十倍，进入高频循环后账单很可观。务必用 prompt caching 复用稳定前缀，并只投喂强相关内容。

  Q5：长上下文会让回答变慢吗？
  会。上下文越长，预填充处理的 token 越多，首字延迟上升。交互式编程场景尤其敏感，缓存 + 精确投喂是必要的优化。

  八、结语

  1M 上下文确实已经可用，但它是一种有成本的资源，不是免费容量。真正的工程能力，体现在你知道什么时候该展开整库、什么时候该退回 RAG 检索——精确投喂，而不是能塞就塞。

  1天前

• CLAUDE.md 怎么写: 提升 Claude Code 准确率的最小有效配置

  社区里流传一句很有冲击力的话：某个项目把 Claude Code 的「准确率从 41% 升到 89%」，靠的只是改了一个 CLAUDE.md。这个数字来自热点原帖的说法，没有公开的评测方法和样本量，我们不把它当作实测基准。但它指向的那件事是真的，而且每个用 Claude Code 写过几天代码的人都体感得到：同一个模型、同一个仓库，给不给项目说明，输出质量差出一个档。

  这篇文章不复述那个跑分故事，而是把它背后的工程问题讲透——CLAUDE.md 到底凭什么影响准确率，一个有效的 CLAUDE.md 该包含哪些块、删掉哪些块，根目录和子目录怎么分层，以及大多数人写它时会踩的几个坑。文末给一份可以直接拿走改的模板骨架。

  为什么一个文本文件能改变准确率

  TL;DR

  CLAUDE.md 是 Claude Code 在每次会话启动时自动读入、拼进系统上下文的项目说明文件。它不是文档，是接口——你用它把「这个项目的真实约束」喂给模型，模型据此决定怎么写代码、跑什么命令、碰什么不能碰。写得准、写得短，模型就少猜；写得乱、写得长，模型的注意力被稀释，反而更容易跑偏。提升准确率的核心不是「写更多」，而是「写对的那几条，并且保持它不过期」。

  机理：这其实是一道上下文工程题

  要理解 CLAUDE.md 为什么有用，得先承认一个事实：大模型对你的项目一无所知。它不知道你的构建命令是 pnpm build 还是 make，不知道你这个仓库里 utils/ 已经废弃、新代码要写进 lib/，不知道你团队约定「不准在 /tmp 留 .php」。没有这些信息时，模型只能靠先验去补——也就是从训练语料里见过的「大多数项目长什么样」来猜你的项目。猜对了是运气，猜错了就是你要返工的那一段。

  CLAUDE.md 做的事，是把模型从「靠先验猜」拉到「靠现场事实推」。这正是上下文工程的核心命题：模型的能力上限由权重决定，但单次任务的发挥由你喂进上下文的信息决定。同一个 Claude，在一个有清晰 CLAUDE.md 的仓库里像个熟悉代码库的同事，在一个空仓库里像个第一天入职、谁也没给他讲过规矩的外包。

  这里有个容易被忽略的反向效应：上下文不是越多越好。模型的注意力是有限资源，你塞进 CLAUDE.md 的每一个字都在和真正重要的约束抢注意力。一份 600 行、把环境变量、历史决策、未来规划全堆进去的 CLAUDE.md，效果往往不如一份 80 行、只讲清楚「项目结构 + 关键命令 + 三条红线」的精简版。这就是为什么这篇文章反复强调最小有效——目标是信噪比，不是信息量。

  如果你对「模型重新打开仓库时从哪里恢复记忆」这件事感兴趣，Claude Code 长项目踩坑: vibe coding 与 spec coding 何时切换 把长项目的上下文恢复问题讲得更系统，CLAUDE.md 正是其中最便宜的一环。

  一个有效的 CLAUDE.md 该有哪些块

  下面逐块拆。每一块都给「为什么需要」和「示例写法」，但请记住：不是每个项目都要全装上，按你仓库的实际复杂度取舍。

  块一：项目是什么（一两句话定位）

  模型需要先知道它在跟什么打交道。一句话说清楚这是个什么项目、用什么技术栈、解决什么问题。不要写市场宣传语，写工程事实。

  ## 项目
  基于 Next.js 14 (App Router) + TypeScript 的内容站。
  数据源是本地 Markdown，构建期静态生成。无后端数据库。
  

  这三行的价值在于：模型从此知道「这里没有数据库」，就不会给你写出连 Prisma 的代码。

  块二：项目结构（只标关键目录，不复述文件树）

  不要把 tree 的输出贴进来——那是噪音。只标注那些「模型必须知道、否则会写错位置」的目录约定。

  ## 结构
  - `lib/`：核心逻辑，新代码写这里
  - `utils/`：已废弃，不要往里加东西
  - `content/`：Markdown 内容源，构建期读取
  - `app/api/`：路由处理，每个文件一个 endpoint
  

  注意「utils/ 已废弃」这种负向约定往往比正向说明更值钱，因为它消除了模型一个最常见的错误猜测。

  块三：关键命令（构建、测试、lint）

  模型经常需要自己跑命令验证改动。如果你不告诉它命令是什么，它会去猜——猜 npm test 结果你用的是 vitest，猜 npm run build 结果你用的是 pnpm。把这几条钉死：

  ## 命令
  - 装依赖：`pnpm install`
  - 开发：`pnpm dev`（端口 3000）
  - 构建：`pnpm build`
  - 测试：`pnpm test`（vitest）
  - 类型检查：`pnpm typecheck`
  

  这一块对「让模型自己验证」的工作流尤其关键。模型能自己跑测试、读报错、再修，这条闭环的起点就是它知道该跑什么命令。

  块四：代码风格与约定

  不要把整个 ESLint 配置抄进来——那有 lint 工具管。这里写的是工具检查不出来、但你团队真在乎的约定。

  ## 约定
  - 组件用函数式 + hooks，不写 class 组件
  - 异步用 async/await，不用 .then 链
  - 错误处理：API 层统一 try/catch，不在组件里裸 fetch
  - 文案中文用全角标点，代码注释用中文
  

  块五：做什么 / 不做什么（红线）

  这是整份文件里密度最高的一块，也是最能拉准确率的一块。把那些「做错了代价很大、回滚很贵」的边界明确列出来。

  ## 红线
  - 不要改 `config/legacy.ts`，那是兼容层，动它会炸老用户
  - 不要在未问的情况下升级主版本依赖
  - 提交信息用 conventional commits 格式
  - 数据库迁移必须可回滚，不写不可逆的 DROP
  

  这一块的写法直接决定了模型会不会闯祸。红线越具体，模型越不容易在你没盯着的时候做出难以挽回的操作。关于「用流程规范约束 AI 行为」，开发者反击”自私”的 AI 滥用：用表情符号暗号与流程规范对抗 LLM 垃圾内容 提供了一个更激进的社区视角，本质上和这里的「红线」是同一类思路。

  块六：按需加载的子文档索引

  CLAUDE.md 本身要短，但有些信息（数据库 schema、复杂模块的设计文档、踩坑记录）确实需要存在。解法是索引而非内联：在主文件里只放一行指针，告诉模型「需要时去读哪个文件」。

  ## 关键文档（按需加载）
  - `docs/db-schema.md`：数据表结构，涉及数据层任务时读
  - `docs/auth-flow.md`：鉴权流程，改登录相关时读
  - `docs/deploy.md`：部署流程与回滚步骤，发布前读
  

  这样主文件保持精简，详细信息又不丢失。模型会在判断任务相关时主动去读那些子文档，而不是一上来就被几千字的 schema 占满上下文。

  目录约定与分层：根 CLAUDE.md 不是唯一一份

  很多人不知道 CLAUDE.md 可以分层。Claude Code 不只读根目录那一份，它会沿着你当前工作的目录路径，把沿途的 CLAUDE.md 都纳入上下文。这给了你一个很自然的「就近说明」机制。

  根目录 CLAUDE.md：全局约定

  放整个仓库都适用的东西：技术栈、全局命令、跨模块的红线、团队风格。这一份要尽量稳定，不该频繁改动。

  子目录 CLAUDE.md：局部上下文

  在一个有独立约定的子目录里放一份局部 CLAUDE.md。比如你的 packages/web/ 和 packages/cli/ 用不同的测试框架、不同的发布流程，就各放一份，写各自的局部规则。模型在 packages/web/ 下干活时，自然带上 web 包的上下文，不会被 cli 包的规则干扰。

  这种分层的好处是信息局部性：每一份文件只对它管辖的范围负责，既避免了根文件无限膨胀，也避免了模型在写 A 模块时被 B 模块的无关信息分心。这其实和「模块化管理配置」是同一个工程直觉——社区里关于配置组织方式的讨论一直没停，开发者吐槽Claude Code配置混乱：pi的模块化管理被指更胜一筹 就是一例，分层 CLAUDE.md 是 Claude Code 自带的、最轻量的模块化手段。

  如果你同时在用多个 AI 编程工具，配置分散是个真问题。社区已经有人在做聚合管理，比如 聚合管理AI编程客户端配置，开源工具SMRmanager v0.2发布 和早一点的 开源神器 SMRmanager：一键统一管理 Claude、Cursor 等 AI 编程工具配置，思路是把多工具的配置集中起来。不过对单一 Claude Code 项目来说，先把分层 CLAUDE.md 写好，收益更直接。

  一份可复用的模板骨架

  下面是一个可以直接拿走改的根目录 CLAUDE.md 模板。它是示例/参考写法，不是官方规范——Claude Code 对 CLAUDE.md 的内容没有强制 schema，你完全可以增删块。保持它在 100 行以内，是这份模板想传达的纪律。

  # CLAUDE.md
  
  ## 项目
  <一两句话：什么项目、什么栈、解决什么问题、有没有后端/数据库>
  
  ## 结构
  - `src/`：<职责>
  - `<已废弃目录>/`：不要往里加东西
  - `<内容/配置目录>/`：<构建期还是运行时用>
  
  ## 命令
  - 装依赖：`<cmd>`
  - 开发：`<cmd>`（端口 <port>）
  - 构建：`<cmd>`
  - 测试：`<cmd>`（<框架>）
  - lint / 类型检查：`<cmd>`
  
  ## 约定
  - <工具检查不出、但团队在乎的风格 1>
  - <约定 2>
  - <约定 3>
  
  ## 红线（做错代价大、回滚贵）
  - 不要改 `<敏感文件>`，原因：<...>
  - 未经确认不要 <危险操作>
  - 提交信息用 <格式>
  - <可回滚要求>
  
  ## 关键文档（按需加载）
  - `docs/<x>.md`：<什么时候读>
  - `docs/<y>.md`：<什么时候读>
  

  子目录 CLAUDE.md 更短，通常只需要「局部命令 + 局部约定 + 局部红线」三块，全局信息靠根文件继承，不要重复。

  值得强调的是：模板是起点不是终点。第一版写出来后，真正让它变准的是迭代——你每次发现模型又跑偏了，就回头问「CLAUDE.md 里缺了哪条说明，导致它这么猜」，把那条补上。几轮之后，这份文件会收敛成你这个项目专属的、密度极高的说明书。这个「发现偏差 → 补一条 → 收敛」的循环，和工程团队用 AI 重写核心模块时的迭代方式是相通的，PostHog 工程实录：利用 AI 重写核心 SQL 解析器，性能暴增 454 倍 里那种长会话、反复校准的打法，靠的也是把项目约束持续喂准。

  常见反模式：好心办坏事的三种写法

  CLAUDE.md 写坏比不写还糟，因为坏的说明会主动误导模型。下面三种是最高频的。

  反模式一：写成一本书

  最常见的错误，是把 CLAUDE.md 当成项目 wiki，恨不得把架构演进史、所有环境变量、每个模块的详细设计全塞进去。结果是几百行的文件，模型读完，真正重要的「红线」被埋在第 300 行，注意力早就分散了。

  修法：主文件砍到 100 行以内，详细内容拆进 docs/ 用「按需加载索引」引用。问自己一个问题：这条信息，是「模型每次都得知道」还是「模型偶尔才用到」？前者留在主文件，后者进子文档。

  反模式二：堆无关信息

  往 CLAUDE.md 里塞模型其实用不上、或者别的工具已经管了的东西。比如把整份 .eslintrc 抄进来（lint 工具会执行，模型不需要读）、把 package.json 的依赖列表复述一遍（模型自己会看 package.json）、写一堆「我们是一个充满激情的团队」之类的废话。

  修法：每一行都过一遍「删掉它，模型会写错吗？」如果不会，就删。CLAUDE.md 的每个字都该是「不写就会出错」的信息。

  反模式三：过期不更新

  这是最隐蔽、危害最大的一种。你三个月前写「测试用 jest」，后来全仓库迁到了 vitest，但 CLAUDE.md 没改。现在模型每次都按 jest 的 API 给你写测试——它不是猜错的，是被你主动喂错的。过期的 CLAUDE.md 比没有 CLAUDE.md 更危险，因为它带着权威感误导。

  修法：把 CLAUDE.md 当代码维护。目录结构变了、命令变了、约定变了，第一时间同步改。最好在团队约定里写一条：「改动构建/测试/目录结构的 PR，必须同步更新 CLAUDE.md」。让它和代码一起进版本控制、一起 review。

  这种「配置漂移导致行为异常」的麻烦，在 Claude Code 的使用反馈里并不少见。当然有些波动并不是 CLAUDE.md 的锅，比如 解决 Claude Code 性能波动难题：用户推测降智与服务器 Session 路由强相关 讨论的是服务端的不确定性。排查输出质量问题时，先确认是「你喂的上下文有问题」还是「服务端确实在抖」，别把所有锅都甩给 CLAUDE.md，也别忽略它。

  把 CLAUDE.md 放进更大的工作流

  CLAUDE.md 不是孤立的。它和你怎么选工具、怎么编排多智能体、怎么管额度，共同决定了 AI 编程的最终体验。

  如果你还在选编程 Agent，Claude Code vs Codex vs WorkBuddy vs Zcode: AI 编程 Agent 怎么选 和 AI编程工具现状：从IDE到CLI，开发者如何在Cursor与Claude间抉择 这两篇能帮你定位——但无论选哪个 CLI 类工具，「给项目写一份精炼的说明文件」这个动作都是通用的，只是文件名不同。

  进阶玩法是多智能体协作，开发者构建多智能体协作流：用GPT Pro指挥Claude Code与Codex 展示了用一个模型指挥另一个模型干活的编排方式，这种场景下每个执行节点都需要清晰的项目上下文，CLAUDE.md 的价值被进一步放大。而 遭遇GPT降智后转向Claude：开发者实测MCP协议打造”自举”式开发闭环 则把 MCP 协议和开发闭环串了起来，CLAUDE.md 在这种闭环里承担的就是「让每一轮都从正确的项目认知出发」。

  成本侧也别忽视。上下文写得精炼，本身就是省 token——一份臃肿的 CLAUDE.md 每次会话都要重新读一遍，长期看是实打实的额度消耗。关于额度，社区最近讨论很多，比如 Claude Code 实战：20篇顶会文献瞬间总结，Opus 额度告急引发成本担忧 和 频繁触发限流？开发者反馈 Claude Code 会话额度疑似大幅收紧，精简上下文虽然不能根治限流，但能让你每一份额度花得更值。

  相关阅读

  • Claude Code 长项目踩坑: vibe coding 与 spec coding 何时切换——CLAUDE.md 是长项目上下文恢复的最便宜一环，这篇讲清楚什么时候该上规格。
  • Claude Code vs Codex vs WorkBuddy vs Zcode: AI 编程 Agent 怎么选——选定工具，再谈配置。
  • 深度解析 Cursor Composer 2.5：从”套壳”争议到拥有工作流数据的巨头护城河——理解工作流数据为什么是护城河，会让你更重视本地上下文资产。
  • AI编程新范式：2026 Vibe Coding全栈实战训练营，整合Cursor与Claude Code——把工具整合进完整工作流的实战视角。

  FAQ

  Q：CLAUDE.md 要放在哪里，Claude Code 会自动读吗？
  A：放在项目根目录，文件名就是 CLAUDE.md。Claude Code 在会话启动时会自动读取并拼入上下文，无需手动指定。子目录里也可以放，模型在该目录下工作时会一并纳入。

  Q：CLAUDE.md 越详细越好吗？
  A：不是。它和真正重要的约束抢模型注意力，过长反而稀释效果。目标是「最小有效」——只写不写就会出错的信息，详细内容拆进 docs/ 按需加载。一般主文件控制在 100 行以内。

  Q：那个「41% 到 89%」的准确率提升是真的吗？
  A：这是社区热点原帖的说法，没有公开的评测方法、样本量和复现步骤，不能当作权威基准。但「写好项目说明文件能显著改善输出质量」这个方向是站得住的，具体能提升多少取决于你的项目和写法。

  Q：CLAUDE.md 和 MCP、子 agent 这些是什么关系？
  A：是互补的不同层。CLAUDE.md 解决「模型该知道这个项目的什么」，MCP 解决「模型能调用什么外部能力」，子 agent 解决「复杂任务怎么拆分编排」。先把 CLAUDE.md 写好，它是成本最低、收益最直接的一层。

  Q：团队协作时 CLAUDE.md 要进版本控制吗？
  A：要。把它当代码维护，进 Git、一起 review，约定「改构建/测试/目录的 PR 必须同步更新它」。过期的 CLAUDE.md 会主动误导模型，比没有还糟。

  结语

  CLAUDE.md 不是文档，是接口：你把项目的真实约束写准、写短、并保持它不过期，模型就从「靠先验猜」切到「靠现场推」。提升准确率的关键从来不是写更多，而是写对那几条。先给你的项目补一份 80 行的精简版，剩下的交给迭代。

  1天前