1. 为什么 Claude Code 需要一套“项目记忆系统”Claude Code 默认是无状态的每次新开会话它只认得当前对话内容加上项目根目录里那份CLAUDE.md。短期任务无所谓但一个跑了三个月、几十个模块、上百次提交的项目问题就会集中爆发——三天前定的架构决策今天要重新解释一遍哪些功能已完成、哪些卡在阻塞项上全靠你脑补同一个坑比如异步函数里混用同步 ORM反复踩AI 改完代码没有版本锚点出问题想回滚都不知道回到哪。我试过最直接的解法就是把“记忆”从对话里搬到文件里再用 Git 给这些文件上版本控制。核心思路是三层指令层用CLAUDE.md定义每次会话自动加载的行为协议上下文层用claude-context/*.md存项目知识、进度、历史、验证记录执行层用执行日志把每次任务和 Git commit 锚定起来。关键认知是——这些上下文文件不是“文档”而是代码的一部分应该和源码一起被版本控制、审查、回溯。这套东西适合谁适合用 Claude Code 或任何支持CLAUDE.md的 AI 编程助手、做长期项目不是一次性脚本的开发者。下面我把可复制的骨架、配置片段和 Git 钩子验证动作拆开讲最后说怎么用 TaoToken 统一 Key/API 通道接进来。2. 前置准备用 TaoToken 统一 Key 与 API 通道在动手写CLAUDE.md之前先把接入通道理顺。Claude Code 这类终端工具需要一个稳定的 API 入口TaoToken 提供统一的 Key 和 API 通道官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 这个地址不加 UTM 参数。操作路径很直接先去控制台创建 Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 拿到 Key 后配置到环境变量里。如果你用的是 Claude Code 的 Anthropic 兼容模式接入文档在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentClaudeCodeAnthropicutm_campaignrewrite 里面有具体的环境变量名和 base_url 写法。# 把 Key 写进 shell 配置避免每次会话重设 export ANTHROPIC_API_KEY你的_TaoToken_Key export ANTHROPIC_BASE_URLhttps://taotoken.net/api配好之后Claude Code 启动时会走这个通道。如果你还想在网页端直接和模型对话验证 Key 是否可用可以打开模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 发一条测试消息。长期做编码和 Agent 任务的话Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 里有套餐说明按自己的调用量选就行。注意Key 只放在环境变量或本地配置里不要提交进 Git。后面07-git-policy.md里会专门列敏感文件保护规则。3. 搭建 claude-context 文件体系与 CLAUDE.md 骨架在项目根目录建一个claude-context/目录放 8 个文件各管一摊你的项目根目录/ ├── CLAUDE.md # 主指令每次会话自动加载 ├── claude-context/ │ ├── 01-project-brief.md # 项目总览、技术栈、ADR │ ├── 02-current-state.md # 当前进度、阻塞项、技术债务 │ ├── 03-execution-log.md # 执行日志 Git 锚点 │ ├── 04-validation-log.md # 测试与验证结果 │ ├── 05-roadmap.md # 路线图与验收标准 │ ├── 06-lessons-learned.md # 踩坑与经验 │ ├── 07-git-policy.md # 分支策略与提交规范 │ └── 08-research-log.md # 文献驱动改进记录 └── .gitignoreCLAUDE.md是整个系统的“宪法”控制在 200 行以内太长规则会被忽略。骨架如下# Claude Code 项目协作指令 v1.0 ## 一、执行前必读 每次操作前按顺序读取 1. claude-context/01-project-brief.md 2. claude-context/02-current-state.md 3. claude-context/05-roadmap.md 4. claude-context/06-lessons-learned.md 5. claude-context/07-git-policy.md 读完后汇报当前 SDLC 阶段、已完成模块、进行中/阻塞、技术债务、下一步建议、Git 状态。 ## 二、执行后必做 1. 在 03-execution-log.md 顶部追加记录含 Git commit hash 2. 更新 02-current-state.md 的功能状态 3. 涉及测试则更新 04-validation-log.md 4. 涉及技术选型则更新 08-research-log.md ## 三、Git 备份协议 - 执行前git status --short 检查工作区有未提交更改先 stash - 执行后git add 具体文件 → git commit -m [Claude] 类型: 简述 - 里程碑git tag -a claude-YYYYMMDD-N ## 四、工作原则 渐进式改进、保留证据、上下文继承、原子化记录、版本锚定。.gitignore里要确保claude-context/不被忽略同时把敏感文件挡在外面# 确保上下文文件纳入版本控制 !claude-context/ # 敏感文件保护 .env *.pem secrets/ config/production.yml CLAUDE.local.md07-git-policy.md里写清分支模型和提交规范这是后面 Git 钩子校验的依据# Git 策略与提交规范 ## 分支模型 - main保护分支禁止直接推送 - feature/xxx新功能 - claude/feature-xxxAI 协作实验 - fix/xxxBug 修复 ## 提交规范 - 格式[Claude] 类型: 简述 - 类型feat / fix / refactor / docs / test / chore / research ## 敏感文件保护 禁止 Claude 直接修改.env, *.pem, secrets/, config/production.yml4. settings.json 配置与 Git 钩子验证光靠CLAUDE.md里的文字约束不够可靠敏感文件写入要用 Hook 硬拦。Claude Code 支持在settings.json里配PreToolUse钩子。在项目根目录建.claude/settings.json{ hooks: { PreToolUse: [ { matcher: Write|Edit, hooks: [ { type: command, command: bash .claude/hooks/guard-sensitive.sh } ] } ] } }对应的守卫脚本.claude/hooks/guard-sensitive.sh从标准输入读工具调用参数命中敏感路径就退出码 2 阻断#!/bin/bash # 读取 Claude Code 传入的 JSON INPUT$(cat) FILE_PATH$(echo $INPUT | grep -o file_path[^,]* | cut -d -f4) case $FILE_PATH in *.env|*.pem|*secrets/*|*config/production.yml) echo 阻断$FILE_PATH 属于敏感文件禁止 AI 直接修改 2 exit 2 ;; esac exit 0给脚本加执行权限chmod x .claude/hooks/guard-sensitive.sh再配一个 Git 提交信息校验钩子强制[Claude]前缀和类型规范。在.git/hooks/commit-msg写入#!/bin/bash MSG$(cat $1) PATTERN^\[Claude\] (feat|fix|refactor|docs|test|chore|research): . if ! echo $MSG | grep -qE $PATTERN; then echo 提交信息不符合规范应为[Claude] 类型: 简述 echo 类型可选feat/fix/refactor/docs/test/chore/research exit 1 fi exit 0chmod x .git/hooks/commit-msg这样每次 AI 提交都会被校验格式不对直接打回。实测下来这两个钩子把“AI 乱改敏感文件”和“提交历史混乱”两个高频问题挡在了源头。5. 验证请求与成功结果配置完成后跑一遍完整流程验证。先确认 Git 环境干净git status --short git rev-parse --short HEAD然后给 Claude Code 发一条初始化指令让它读取现有项目文档、扫描目录结构、生成 8 个上下文文件并提交任务为项目建立 Claude Code 上下文管理系统 1. 读取项目现有文档理解模块划分 2. 扫描目录结构排除 node_modules/.git/__pycache__ 3. 检查 .gitignore 确保 claude-context/ 不被忽略 4. 创建 claude-context/ 下 8 个文件 5. 创建 CLAUDE.md 主指令 6. git add claude-context/ CLAUDE.md 7. git commit -m [Claude] docs: 初始化项目上下文管理系统 8. git tag -a claude-20260529-1 -m [Claude] 里程碑: 记忆系统初始化执行后检查结果。提交信息校验钩子应该放行合规提交git log --oneline -3 # 预期输出类似 # d4e5f6g [Claude] docs: 初始化项目上下文管理系统标签也确认一下git tag --list claude-* # claude-20260529-1再测一次敏感文件拦截。让 Claude 尝试写.env钩子应该返回阻断信息工具调用被拒绝文件内容不变。这一步验证通过说明“文字约束 硬钩子”双层防护生效了。最后验证上下文继承新开一个会话输入“读取上下文准备开始工作”Claude 应该自动读取 5 个必读文件并汇报当前阶段、进度、阻塞项和 Git 状态。如果它能准确说出上次提交的 hash 和进行中的任务说明记忆系统跑通了。6. 本篇常见错误与排障Claude 不读取上下文文件。最常见原因是CLAUDE.md太长超过 200 行或规则模糊。精简主指令只留不可省略的规则细节移到claude-context/各文件里。另外确认文件名大小写完全一致CLAUDE.md不是claude.md。Claude 忽略 Git 协议。指令被其他内容淹没了。在CLAUDE.md里用明确的触发词机制比如“更新日志”“项目体检”或者在07-git-policy.md里单独强调。必要时用PreToolUse钩子强制检查。上下文文件与实际代码脱节。更新不及时导致的。在CLAUDE.md的“执行后必做”里强化约束把更新上下文文件列为任务完成的必要条件而不是可选项。提交信息校验钩子误伤。如果钩子报错但信息看着没问题检查正则里的空格和冒号——[Claude] feat: xxx中]后有一个空格:后也有一个空格。用echo 测试信息 | grep -E 你的正则单独测一下。敏感文件钩子没生效。确认.claude/settings.json的路径和matcher写对了Write|Edit要覆盖实际使用的工具名。脚本路径用相对项目根目录的写法并确认有执行权限。Git 提交历史混乱。一次提交包含过多无关改动。要求 Claude 用“精准添加”git add具体文件而非git add -A并在03-execution-log.md里记录变更文件清单方便回溯。文献调研结果不可靠。来源可信度低。严格执行可信度分级官方文档和学术论文可直接作为决策依据知名技术博客需交叉验证无署名无日期的内容只能当线索。每个改进决策都要能回溯到08-research-log.md里的具体记录。7. 把记忆系统接进日常 SDLC 流程系统搭好后日常协作会变得高度标准化。需求分析阶段Claude 读01-project-brief.md和05-roadmap.md把需求拆成可执行任务写回路线图设计阶段读06-lessons-learned.md避免历史错误把技术选型记进08-research-log.md开发阶段按07-git-policy.md的分支规范走每次提交都带 Git 锚点测试阶段对比04-validation-log.md里的历史基线判断改进还是退化部署和维护阶段靠标签和日志快速定位版本。这套流程要跑顺API 通道得稳定。TaoToken 的 Key 和 API 端点统一管理Claude Code 通过 Anthropic 兼容模式接入接入文档在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentClaudeCodeAnthropicutm_campaignrewrite 。如果你同时跑多个 Agent 会话做并行开发Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 里有对应的调用方案。Key 管理在控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 需要新建或轮换 Key 时去那里操作。一个实用技巧用git worktree给不同任务开独立工作树每个目录跑一个 Claude 会话一个写代码一个做审查互不干扰。配合claude-context/的共享记忆两个会话看到的是同一份项目状态但改动隔离在各自分支里合并前用04-validation-log.md的基准数据做对比。这样跑一个月Claude 就不再是每次都要重新解释项目的临时工而是记得你的技术债务、架构决策和踩坑记录的长期协作者。 Claude Code 项目记忆系统完全指南：用 CLAUDE.md 与 Git 打通 SDLC 配置实战
1. 为什么 Claude Code 需要一套“项目记忆系统”Claude Code 默认是无状态的每次新开会话它只认得当前对话内容加上项目根目录里那份CLAUDE.md。短期任务无所谓但一个跑了三个月、几十个模块、上百次提交的项目问题就会集中爆发——三天前定的架构决策今天要重新解释一遍哪些功能已完成、哪些卡在阻塞项上全靠你脑补同一个坑比如异步函数里混用同步 ORM反复踩AI 改完代码没有版本锚点出问题想回滚都不知道回到哪。我试过最直接的解法就是把“记忆”从对话里搬到文件里再用 Git 给这些文件上版本控制。核心思路是三层指令层用CLAUDE.md定义每次会话自动加载的行为协议上下文层用claude-context/*.md存项目知识、进度、历史、验证记录执行层用执行日志把每次任务和 Git commit 锚定起来。关键认知是——这些上下文文件不是“文档”而是代码的一部分应该和源码一起被版本控制、审查、回溯。这套东西适合谁适合用 Claude Code 或任何支持CLAUDE.md的 AI 编程助手、做长期项目不是一次性脚本的开发者。下面我把可复制的骨架、配置片段和 Git 钩子验证动作拆开讲最后说怎么用 TaoToken 统一 Key/API 通道接进来。2. 前置准备用 TaoToken 统一 Key 与 API 通道在动手写CLAUDE.md之前先把接入通道理顺。Claude Code 这类终端工具需要一个稳定的 API 入口TaoToken 提供统一的 Key 和 API 通道官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 这个地址不加 UTM 参数。操作路径很直接先去控制台创建 Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 拿到 Key 后配置到环境变量里。如果你用的是 Claude Code 的 Anthropic 兼容模式接入文档在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentClaudeCodeAnthropicutm_campaignrewrite 里面有具体的环境变量名和 base_url 写法。# 把 Key 写进 shell 配置避免每次会话重设 export ANTHROPIC_API_KEY你的_TaoToken_Key export ANTHROPIC_BASE_URLhttps://taotoken.net/api配好之后Claude Code 启动时会走这个通道。如果你还想在网页端直接和模型对话验证 Key 是否可用可以打开模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 发一条测试消息。长期做编码和 Agent 任务的话Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 里有套餐说明按自己的调用量选就行。注意Key 只放在环境变量或本地配置里不要提交进 Git。后面07-git-policy.md里会专门列敏感文件保护规则。3. 搭建 claude-context 文件体系与 CLAUDE.md 骨架在项目根目录建一个claude-context/目录放 8 个文件各管一摊你的项目根目录/ ├── CLAUDE.md # 主指令每次会话自动加载 ├── claude-context/ │ ├── 01-project-brief.md # 项目总览、技术栈、ADR │ ├── 02-current-state.md # 当前进度、阻塞项、技术债务 │ ├── 03-execution-log.md # 执行日志 Git 锚点 │ ├── 04-validation-log.md # 测试与验证结果 │ ├── 05-roadmap.md # 路线图与验收标准 │ ├── 06-lessons-learned.md # 踩坑与经验 │ ├── 07-git-policy.md # 分支策略与提交规范 │ └── 08-research-log.md # 文献驱动改进记录 └── .gitignoreCLAUDE.md是整个系统的“宪法”控制在 200 行以内太长规则会被忽略。骨架如下# Claude Code 项目协作指令 v1.0 ## 一、执行前必读 每次操作前按顺序读取 1. claude-context/01-project-brief.md 2. claude-context/02-current-state.md 3. claude-context/05-roadmap.md 4. claude-context/06-lessons-learned.md 5. claude-context/07-git-policy.md 读完后汇报当前 SDLC 阶段、已完成模块、进行中/阻塞、技术债务、下一步建议、Git 状态。 ## 二、执行后必做 1. 在 03-execution-log.md 顶部追加记录含 Git commit hash 2. 更新 02-current-state.md 的功能状态 3. 涉及测试则更新 04-validation-log.md 4. 涉及技术选型则更新 08-research-log.md ## 三、Git 备份协议 - 执行前git status --short 检查工作区有未提交更改先 stash - 执行后git add 具体文件 → git commit -m [Claude] 类型: 简述 - 里程碑git tag -a claude-YYYYMMDD-N ## 四、工作原则 渐进式改进、保留证据、上下文继承、原子化记录、版本锚定。.gitignore里要确保claude-context/不被忽略同时把敏感文件挡在外面# 确保上下文文件纳入版本控制 !claude-context/ # 敏感文件保护 .env *.pem secrets/ config/production.yml CLAUDE.local.md07-git-policy.md里写清分支模型和提交规范这是后面 Git 钩子校验的依据# Git 策略与提交规范 ## 分支模型 - main保护分支禁止直接推送 - feature/xxx新功能 - claude/feature-xxxAI 协作实验 - fix/xxxBug 修复 ## 提交规范 - 格式[Claude] 类型: 简述 - 类型feat / fix / refactor / docs / test / chore / research ## 敏感文件保护 禁止 Claude 直接修改.env, *.pem, secrets/, config/production.yml4. settings.json 配置与 Git 钩子验证光靠CLAUDE.md里的文字约束不够可靠敏感文件写入要用 Hook 硬拦。Claude Code 支持在settings.json里配PreToolUse钩子。在项目根目录建.claude/settings.json{ hooks: { PreToolUse: [ { matcher: Write|Edit, hooks: [ { type: command, command: bash .claude/hooks/guard-sensitive.sh } ] } ] } }对应的守卫脚本.claude/hooks/guard-sensitive.sh从标准输入读工具调用参数命中敏感路径就退出码 2 阻断#!/bin/bash # 读取 Claude Code 传入的 JSON INPUT$(cat) FILE_PATH$(echo $INPUT | grep -o file_path[^,]* | cut -d -f4) case $FILE_PATH in *.env|*.pem|*secrets/*|*config/production.yml) echo 阻断$FILE_PATH 属于敏感文件禁止 AI 直接修改 2 exit 2 ;; esac exit 0给脚本加执行权限chmod x .claude/hooks/guard-sensitive.sh再配一个 Git 提交信息校验钩子强制[Claude]前缀和类型规范。在.git/hooks/commit-msg写入#!/bin/bash MSG$(cat $1) PATTERN^\[Claude\] (feat|fix|refactor|docs|test|chore|research): . if ! echo $MSG | grep -qE $PATTERN; then echo 提交信息不符合规范应为[Claude] 类型: 简述 echo 类型可选feat/fix/refactor/docs/test/chore/research exit 1 fi exit 0chmod x .git/hooks/commit-msg这样每次 AI 提交都会被校验格式不对直接打回。实测下来这两个钩子把“AI 乱改敏感文件”和“提交历史混乱”两个高频问题挡在了源头。5. 验证请求与成功结果配置完成后跑一遍完整流程验证。先确认 Git 环境干净git status --short git rev-parse --short HEAD然后给 Claude Code 发一条初始化指令让它读取现有项目文档、扫描目录结构、生成 8 个上下文文件并提交任务为项目建立 Claude Code 上下文管理系统 1. 读取项目现有文档理解模块划分 2. 扫描目录结构排除 node_modules/.git/__pycache__ 3. 检查 .gitignore 确保 claude-context/ 不被忽略 4. 创建 claude-context/ 下 8 个文件 5. 创建 CLAUDE.md 主指令 6. git add claude-context/ CLAUDE.md 7. git commit -m [Claude] docs: 初始化项目上下文管理系统 8. git tag -a claude-20260529-1 -m [Claude] 里程碑: 记忆系统初始化执行后检查结果。提交信息校验钩子应该放行合规提交git log --oneline -3 # 预期输出类似 # d4e5f6g [Claude] docs: 初始化项目上下文管理系统标签也确认一下git tag --list claude-* # claude-20260529-1再测一次敏感文件拦截。让 Claude 尝试写.env钩子应该返回阻断信息工具调用被拒绝文件内容不变。这一步验证通过说明“文字约束 硬钩子”双层防护生效了。最后验证上下文继承新开一个会话输入“读取上下文准备开始工作”Claude 应该自动读取 5 个必读文件并汇报当前阶段、进度、阻塞项和 Git 状态。如果它能准确说出上次提交的 hash 和进行中的任务说明记忆系统跑通了。6. 本篇常见错误与排障Claude 不读取上下文文件。最常见原因是CLAUDE.md太长超过 200 行或规则模糊。精简主指令只留不可省略的规则细节移到claude-context/各文件里。另外确认文件名大小写完全一致CLAUDE.md不是claude.md。Claude 忽略 Git 协议。指令被其他内容淹没了。在CLAUDE.md里用明确的触发词机制比如“更新日志”“项目体检”或者在07-git-policy.md里单独强调。必要时用PreToolUse钩子强制检查。上下文文件与实际代码脱节。更新不及时导致的。在CLAUDE.md的“执行后必做”里强化约束把更新上下文文件列为任务完成的必要条件而不是可选项。提交信息校验钩子误伤。如果钩子报错但信息看着没问题检查正则里的空格和冒号——[Claude] feat: xxx中]后有一个空格:后也有一个空格。用echo 测试信息 | grep -E 你的正则单独测一下。敏感文件钩子没生效。确认.claude/settings.json的路径和matcher写对了Write|Edit要覆盖实际使用的工具名。脚本路径用相对项目根目录的写法并确认有执行权限。Git 提交历史混乱。一次提交包含过多无关改动。要求 Claude 用“精准添加”git add具体文件而非git add -A并在03-execution-log.md里记录变更文件清单方便回溯。文献调研结果不可靠。来源可信度低。严格执行可信度分级官方文档和学术论文可直接作为决策依据知名技术博客需交叉验证无署名无日期的内容只能当线索。每个改进决策都要能回溯到08-research-log.md里的具体记录。7. 把记忆系统接进日常 SDLC 流程系统搭好后日常协作会变得高度标准化。需求分析阶段Claude 读01-project-brief.md和05-roadmap.md把需求拆成可执行任务写回路线图设计阶段读06-lessons-learned.md避免历史错误把技术选型记进08-research-log.md开发阶段按07-git-policy.md的分支规范走每次提交都带 Git 锚点测试阶段对比04-validation-log.md里的历史基线判断改进还是退化部署和维护阶段靠标签和日志快速定位版本。这套流程要跑顺API 通道得稳定。TaoToken 的 Key 和 API 端点统一管理Claude Code 通过 Anthropic 兼容模式接入接入文档在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentClaudeCodeAnthropicutm_campaignrewrite 。如果你同时跑多个 Agent 会话做并行开发Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 里有对应的调用方案。Key 管理在控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 需要新建或轮换 Key 时去那里操作。一个实用技巧用git worktree给不同任务开独立工作树每个目录跑一个 Claude 会话一个写代码一个做审查互不干扰。配合claude-context/的共享记忆两个会话看到的是同一份项目状态但改动隔离在各自分支里合并前用04-validation-log.md的基准数据做对比。这样跑一个月Claude 就不再是每次都要重新解释项目的临时工而是记得你的技术债务、架构决策和踩坑记录的长期协作者。