agents-project-memory

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Memory for Claude Code + Codex (Jan 2026)

Claude Code + Codex 项目内存配置（2026年1月）

Configure project memory so Claude Code and Codex get stable, scoped instructions across sessions while keeping token cost low. Use a single source of truth: keep

AGENTS.md

as primary and symlink

CLAUDE.md

to it.

配置项目内存，让Claude Code和Codex在不同会话中获取稳定、范围明确的指令，同时降低token成本。使用单一可信源：将

AGENTS.md

作为主文件，并将

CLAUDE.md

设为其符号链接。

Quick Reference

快速参考

Memory Type	Typical Location	Purpose
Managed policy	OS-dependent (see official docs)	Organization-wide standards (security, compliance)
Project memory	`./AGENTS.md` (primary) + `./CLAUDE.md` (symlink → AGENTS.md)	Shared project context and conventions
Project rules	`./.claude/rules/*.md`	Modular, topic-focused rules (testing, security, style)
User memory	`~/.claude/CLAUDE.md`	Personal preferences across projects
Project memory (local)	`./CLAUDE.local.md` (git-ignored)	Local-only, project-specific preferences

内存类型	典型位置	用途
管理策略	取决于操作系统（详见官方文档）	全组织范围的标准（安全、合规）
项目内存	`./AGENTS.md` （主文件） + `./CLAUDE.md` （符号链接 → AGENTS.md）	共享项目上下文与约定
项目规则	`./.claude/rules/*.md`	模块化、按主题划分的规则（测试、安全、风格）
用户内存	`~/.claude/CLAUDE.md`	跨项目的个人偏好设置
本地项目内存	`./CLAUDE.local.md` （Git忽略）	仅本地生效的项目特定偏好

How Loading Works (High Level)

加载机制（概述）

Claude Code (CLAUDE.md symlink):

Recursive loading: from the current working directory up to (but not including) filesystem root (
```
/
```
).
On-demand loading: nested
```
CLAUDE.md
```
files under the cwd are loaded only when Claude reads files in those subtrees.
Imports:
```
@path/to/file
```
pulls in additional context (max depth: 5;
```
~
```
supported).

Codex (AGENTS.md primary):

Reads
```
AGENTS.md
```
in the repo root or working directory.
Keep it concise; mirror the same content as
```
CLAUDE.md
```
when supporting both tools.

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

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

Codex（AGENTS.md主文件）:

读取仓库根目录或工作目录中的
```
AGENTS.md
```
文件。
保持内容简洁；同时支持两款工具时，需与
```
CLAUDE.md
```
内容保持一致。

Workflow (Best Practice)

工作流（最佳实践）

Start with a minimal primary memory file (AGENTS.md, 50–120 lines): what the project is, how it's shaped, and the "must not break" rules.
Move long or fragile guidance into
```
.claude/rules/
```
(one topic per file).
Use
```
@imports
```
as navigation for detailed docs instead of copying them into memory.
Treat memory like code: PR review, ownership, and periodic cleanup (remove dead rules).
For UI changes, confirm the specific values (colors, prices, text) before starting implementation to avoid rework.
For feature delivery, prefer one worktree per feature, run project quality gates, then open one focused PR.

从极简的主内存文件（AGENTS.md，50–120行）开始：说明项目内容、架构以及“绝对不能破坏”的规则。
将冗长或易变的指引移至
```
.claude/rules/
```
目录（每个主题对应一个文件）。
使用
```
@imports
```
链接到详细文档，而非将内容复制到内存文件中。
像对待代码一样对待内存文件：进行PR评审、明确所有权并定期清理（移除过时规则）。
进行UI变更时，先确认具体参数（颜色、价格、文本）再开始实现，避免返工。
交付功能时，建议为每个功能使用单独的工作树，运行项目质量检查门，再提交一个聚焦的PR。

Execution Workflow (Worktree + Gate + PR)

执行工作流（工作树 + 检查门 + PR）

When repositories include a workflow script (for example

scripts/git/feature-workflow.sh

), prefer this sequence for AI coding sessions:

bash

undefined

当仓库包含工作流脚本（例如

scripts/git/feature-workflow.sh

）时，AI编码会话建议遵循以下流程：

bash

undefined

1) Create isolated branch/worktree

1) 创建独立分支/工作树

./scripts/git/feature-workflow.sh start <feature-slug> cd .worktrees/<feature-slug>

2) Implement + commit

2) 实现并提交

git add -A git commit -m "feat: <summary>"

3) Run project quality gate (example)

3) 运行项目质量检查门（示例）

../../scripts/git/feature-workflow.sh gate

4) Open PR (gate may run again)

4) 提交PR（检查门可能会再次运行）

../../scripts/git/feature-workflow.sh pr --title "feat: <summary>"


If no helper script exists, use native git worktrees and apply the same policy:
- one feature per worktree
- one focused PR per feature
- run repo-specific gate(s) before PR creation

../../scripts/git/feature-workflow.sh pr --title "feat: <summary>"


如果没有辅助脚本，可使用原生Git工作树并遵循相同策略：
- 每个功能对应一个工作树
- 每个功能对应一个聚焦的PR
- 提交PR前运行仓库特定的检查门

Rules With Optional Path Scope

带可选路径范围的规则

Create

.claude/rules/testing.md

.claude/rules/security.md

, etc. If a rule only applies to a slice of the repo, scope it:

yaml

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

创建

.claude/rules/testing.md

、

.claude/rules/security.md

等文件。如果某条规则仅适用于仓库的部分目录，可设置范围：

yaml

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

Commands (Claude Code)

命令（Claude Code）

```
> /memory
```
to view and directly edit memories.
```
> /init
```
to bootstrap project memory (see official docs for current behavior).

```
> /memory
```
：查看并直接编辑内存文件。
```
> /init
```
：初始化项目内存（当前行为详见官方文档）。

Commands (Codex)

命令（Codex）

Edit
```
AGENTS.md
```
directly; no special memory command is required.

直接编辑
```
AGENTS.md
```
；无需特殊内存命令。

Cross-Platform Strategy (AGENTS.md + CLAUDE.md)

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

If you support multiple coding assistants, keep one canonical file and mirror it:

macOS/Linux:
```
CLAUDE.md
```
should be a symlink to
```
AGENTS.md
```
.
Windows: prefer copying (or a small sync script) over symlinks unless Developer Mode is enabled.

Avoid tool-specific claims in the memory file; keep it portable and strictly project-focused.

如果同时支持多款编码助手，需维护一个标准文件并同步内容：

macOS/Linux：将
```
CLAUDE.md
```
设为
```
AGENTS.md
```
的符号链接。
Windows：除非启用开发者模式，否则建议复制文件（或使用小型同步脚本）而非符号链接。

避免在内存文件中加入工具专属内容；保持文件可移植性，严格聚焦项目本身。

Token-Budget Profile for Project Memory

项目内存的Token预算配置

When sessions repeatedly include very large memory payloads, apply this compact profile.

当会话反复加载超大内存内容时，可采用以下精简配置。

Compact Profile Rules

精简配置规则

Keep
```
AGENTS.md
```
short (target 50-120 lines).
Move long catalogs/checklists to skill docs and reference them by path.
Keep one canonical policy statement per topic; link instead of repeating.
Prefer "read-on-demand" instructions over embedding full inventories in every session.
Maintain a short runtime memory and a fuller reference doc when needed.

保持
```
AGENTS.md
```
简短（目标50-120行）。
将冗长的目录/清单移至技能文档，并通过路径引用。
每个主题仅保留一个标准声明；使用链接而非重复内容。
优先使用“按需读取”指令，而非在每个会话中嵌入完整清单。
必要时，维护一个简短的运行时内存和一个更完整的参考文档。

Suggested Split

建议拆分方式

```
AGENTS.md
```
(runtime): project goal, hard constraints, workflow rules, critical safety constraints.
```
docs/*
```
or skill references: long lists, examples, optional playbooks, large inventories.

```
AGENTS.md
```
（运行时）：项目目标、硬性约束、工作流规则、关键安全限制。
```
docs/*
```
或技能参考：长列表、示例、可选操作手册、大型清单。

Quality Gate

质量检查门

If startup memory exceeds practical context budgets, trim before adding new rules.

如果启动内存超出实际上下文预算，添加新规则前需先精简内容。

Validation (Fast Checks)

验证（快速检查）

Run the bundled linter:

bash frameworks/shared-skills/skills/agents-project-memory/scripts/lint_claude_memory.sh .

Manually scan for unresolved
```
@imports
```
and secrets before merging memory changes.

运行内置的检查工具：

bash frameworks/shared-skills/skills/agents-project-memory/scripts/lint_claude_memory.sh .

合并内存文件变更前，手动检查未解析的
```
@imports
```
和敏感信息。

Resources

资源

Resource	Purpose
references/memory-patterns.md	Patterns and anti-patterns
references/memory-examples.md	Full examples by stack
references/large-codebase-strategy.md	100K–1M LOC strategy
data/sources.json	Official links

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

Skill	Purpose
agents-skills	Skill creation patterns
agents-subagents	Agent/subagent setup
docs-codebase	Repo documentation patterns

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