mcpField
A
agents-project-memory

agents-project-memory

github.com/vasilyu1983Agent 工作流142 次安装
代码仓库

关于 agents-project-memory

为 Claude Code 和 Codex 配置跨会话、按项目生效的记忆与规则的技能。它建议以 AGENTS.md 为单一来源，并用模块化规则、按需引用和精简内容控制上下文开销。

主要功能

  1. 01以 AGENTS.md 作为主要项目记忆
  2. 02通过 CLAUDE.md 链接共享内容
  3. 03按主题拆分 Claude Code 规则
  4. 04提供 worktree、质量门禁与 PR 工作流建议
  5. 05包含记忆文件检查脚本

适用场景

  1. 01为 Claude Code 与 Codex 统一项目约定
  2. 02将冗长规则拆分为按需读取的文件
  3. 03检查记忆文件中的导入路径与密钥

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/vasilyu1983/ai-agents-public --skill agents-project-memory

安装后在 Claude Code 中输入/agents-project-memory确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

data/
sources.json
references/
large-codebase-strategy.md
memory-examples.md
memory-patterns.md
scripts/
lint_claude_memory.sh

详细介绍

Claude Code + Codex 项目记忆（2026 年 1 月）

配置项目记忆，让 Claude Code 和 Codex 在不同会话中获得稳定且范围明确的指示，同时降低 token 成本。使用唯一真实来源：将 AGENTS.md 设为主文件，并创建指向它的 CLAUDE.md 符号链接。

快速参考

记忆类型常见位置用途
托管策略取决于操作系统（参见官方文档）组织范围的标准（安全、合规）
项目记忆./AGENTS.md（主文件）+ ./CLAUDE.md（指向 AGENTS.md 的符号链接）共享项目背景和约定
项目规则./.claude/rules/*.md模块化、按主题划分的规则（测试、安全、风格）
用户记忆~/.claude/CLAUDE.md跨项目的个人偏好
项目记忆（本地）./CLAUDE.local.md（被 Git 忽略）仅本地适用的项目专属偏好
加载方式（概览）

Claude Code（CLAUDE.md 符号链接）：

  • 递归加载：从当前工作目录向上查找，但不包括文件系统根目录（/）。
  • 按需加载：cwd 下的嵌套 CLAUDE.md 文件仅在 Claude 读取对应子目录中的文件时加载。
  • 导入：@path/to/file 会引入额外上下文（最大深度：5；支持 ~）。

Codex（以 AGENTS.md 为主文件）：

  • 读取仓库根目录或工作目录中的 AGENTS.md。
  • 保持内容简洁；同时支持这两个工具时，让它与 CLAUDE.md 内容一致。

工作流（最佳实践）

  1. 从精简的主记忆文件（AGENTS.md，50–120 行）开始：说明项目是什么、结构如何，以及“绝不能破坏”的规则。
  2. 将冗长或易变的指南移至 .claude/rules/（每个文件一个主题）。
  3. 使用 @imports 作为详细文档的导航，而不是将文档复制到记忆文件中。
  4. 像对待代码一样管理记忆：进行 PR 审查、明确所有权，并定期清理（删除失效规则）。
  5. 对于 UI 变更，在开始实现前确认具体值（颜色、价格、文本），避免返工。
  6. 交付功能时，优先为每项功能使用一个 worktree，运行项目质量检查，然后提交一个重点明确的 PR。

执行工作流（Worktree + Gate + PR）

当仓库包含工作流脚本时（例如 scripts/git/feature-workflow.sh），AI 编码会话优先采用以下流程：

# 1) Create isolated branch/worktree
./scripts/git/feature-workflow.sh start <feature-slug>
cd .worktrees/<feature-slug>

# 2) Implement + commit
git add -A
git commit -m "feat: <summary>"

# 3) Run project quality gate (example)
../../scripts/git/feature-workflow.sh gate

# 4) Open PR (gate may run again)
../../scripts/git/feature-workflow.sh pr --title "feat: <summary>"

如果没有辅助脚本，则使用原生 Git worktree，并遵循相同策略：

  • 每个 worktree 对应一项功能
  • 每项功能提交一个重点明确的 PR
  • 创建 PR 前运行仓库专属的检查关卡

可选路径范围的规则

创建 .claude/rules/testing.md、.claude/rules/security.md 等文件。如果某条规则只适用于仓库的一部分，则为其限定适用范围：

---
paths:
  - "src/api/**/*.ts"
---

命令（Claude Code）

  • > /memory 可查看并直接编辑记忆。
  • > /init 可初始化项目记忆（当前行为请参阅官方文档）。

命令（Codex）

  • 直接编辑 AGENTS.md；无需专门的记忆命令。

跨平台策略（AGENTS.md + CLAUDE.md）

如果支持多个编码助手，请保留一个规范文件并同步其内容：

  • macOS/Linux：CLAUDE.md 应为指向 AGENTS.md 的符号链接。
  • Windows：除非启用了开发者模式，否则优先复制文件（或使用简易同步脚本），而不是创建符号链接。

避免在记忆文件中写入特定工具的说明；保持其可移植性，并严格围绕项目内容。

项目记忆的 Token 预算配置

当会话反复包含超大的记忆载荷时，采用此精简配置。

精简配置规则
  1. 保持 AGENTS.md 简短（目标为 50–120 行）。
  2. 将冗长的目录或检查清单移至技能文档，并通过路径引用。
  3. 每个主题只保留一条规范策略；通过链接引用，而不是重复内容。
  4. 优先采用“按需读取”指示，而不是在每个会话中嵌入完整清单。
  5. 按需维护简短的运行时记忆和更完整的参考文档。
建议拆分
  • AGENTS.md（运行时）：项目目标、硬性约束、工作流规则和关键安全约束。
  • docs/* 或技能参考：长列表、示例、可选操作指南和大型清单。
质量门槛

如果启动记忆超出实际可用的上下文预算，应先精简，再添加新规则。

验证（快速检查）

  • 运行附带的代码检查器：bash frameworks/shared-skills/skills/agents-project-memory/scripts/lint_claude_memory.sh .
  • 合并记忆变更前，手动检查是否存在未解析的 @imports 和密钥。

资源

资源用途
references/memory-patterns.md模式和反模式
references/memory-examples.md按技术栈分类的完整示例
references/large-codebase-strategy.md10 万至 100 万行代码的策略
data/sources.json官方链接

相关技能

技能用途
agents-skills技能创建模式
agents-subagentsAgent/子 Agent 设置
docs-codebase仓库文档模式

事实核查

  • 在给出最终答复前，使用网络搜索/网页抓取核实当前的外部事实、版本、定价、截止日期、法规或平台行为。
  • 优先使用一手来源；对于时效性较强的信息，注明来源链接和日期。
  • 如果无法访问网络，应说明这一限制，并标明相关指导未经核实。

评论

支持 Markdown