maintaining-project-context

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Maintaining Project Context

维护项目上下文

REQUIRED SUB-SKILL: Use ed3d-extending-claude:writing-claude-md-files for all context file creation and updates.

必备子技能： 所有上下文文件的创建和更新均需使用ed3d-extending-claude:writing-claude-md-files技能。

Core Principle

核心原则

Context files (CLAUDE.md or AGENTS.md) document contracts and architectural intent. When code changes contracts, the documentation must update. Stale documentation is worse than no documentation.

Trigger: End of development phase, branch completion, or any work that changed contracts, APIs, or domain structure.

上下文文件（CLAUDE.md或AGENTS.md）用于记录契约和架构意图。当代码变更契约时，文档必须同步更新。过时的文档比没有文档更糟糕。

触发时机： 开发阶段结束、分支完成，或任何涉及契约、API或领域结构变更的工作。

Format Detection (MANDATORY FIRST STEP)

格式检测（强制第一步）

Before any updates, detect what format this repository uses:

bash

undefined

在进行任何更新前，先检测当前仓库使用的格式：

bash

undefined

Check for AGENTS.md at root

检查根目录下是否存在AGENTS.md

ls -la AGENTS.md 2>/dev/null

Check for CLAUDE.md at root

检查根目录下是否存在CLAUDE.md

ls -la CLAUDE.md 2>/dev/null


| Root AGENTS.md? | Format | Action |
|-----------------|--------|--------|
| Yes | AGENTS.md-canonical | Update AGENTS.md files, create companion CLAUDE.md |
| No | CLAUDE.md-canonical | Update CLAUDE.md files directly |

**Key principle:** We use OUR format structure (Purpose, Contracts, Dependencies, Invariants, etc.) regardless of filename. AGENTS.md is just for cross-platform AI agent compatibility.

ls -la CLAUDE.md 2>/dev/null


| 根目录存在AGENTS.md？ | 格式 | 操作 |
|-----------------|--------|--------|
| 是 | AGENTS.md标准格式 | 更新AGENTS.md文件，创建配套的CLAUDE.md |
| 否 | CLAUDE.md标准格式 | 直接更新CLAUDE.md文件 |

**关键原则：** 无论文件名是什么，我们都使用自己的格式结构（Purpose、Contracts、Dependencies、Invariants等）。AGENTS.md仅用于跨平台AI Agent兼容性。

AGENTS.md-Canonical Repos

AGENTS.md标准格式仓库

When the repo uses AGENTS.md:

Read AGENTS.md first before making any updates
Write content to AGENTS.md using our standard structure
Create companion CLAUDE.md next to each AGENTS.md with exactly this content:

markdown

Read @./AGENTS.md and treat its contents as if they were in CLAUDE.md

当仓库使用AGENTS.md时：

先阅读AGENTS.md，再进行任何更新
使用标准结构向AGENTS.md写入内容
创建配套的CLAUDE.md，放在每个AGENTS.md旁边，内容严格为：

markdown

Read @./AGENTS.md and treat its contents as if they were in CLAUDE.md

When to Update Context Files

何时更新上下文文件

Change Type	Update Required?	What to Update
New domain/module	Yes	Create domain context file
API/interface change	Yes	Contracts section
Architectural decision	Yes	Key Decisions section
Invariant change	Yes	Invariants section
Dependency change	Yes	Dependencies section
Bug fix (no contract change)	No	-
Refactor (same behavior)	No	-
Test additions	No	-

变更类型	是否需要更新	更新内容
新增领域/模块	是	创建领域上下文文件
API/接口变更	是	Contracts部分
架构决策	是	Key Decisions部分
不变量变更	是	Invariants部分
依赖变更	是	Dependencies部分
修复Bug（未变更契约）	否	-
重构（行为不变）	否	-
新增测试	否	-

The Process

操作流程

Step 1: Identify What Changed

步骤1：识别变更内容

Diff against the base (branch start or phase start):

bash

undefined

与基准版本（分支起始或阶段起始）对比差异：

bash

undefined

Get changed files

获取变更的文件列表

git diff --name-only <base-sha> HEAD

Get detailed changes

获取详细变更统计

git diff <base-sha> HEAD --stat


Categorize changes:
- **Structural:** New directories, moved files
- **Contract:** Changed exports, interfaces, public APIs
- **Behavioral:** Changed invariants, guarantees
- **Internal:** Implementation details only

git diff <base-sha> HEAD --stat


对变更进行分类：
- **结构性变更：** 新增目录、移动文件
- **契约变更：** 变更导出内容、接口、公共API
- **行为变更：** 变更不变量、保证条款
- **内部变更：** 仅实现细节变更

Step 2: Map Changes to Context Files

步骤2：映射变更到上下文文件

For each significant change, determine which context file should document it:

Change Location	Context File Location
Project-wide pattern	Root context file
New domain	`<domain>/` context file (create)
Existing domain contract	`<domain>/` context file (update)
Cross-domain dependency	Both affected domains

Hierarchy rule: Information belongs at the lowest level where it applies. Domain-specific contracts go in domain files, not root.

For AGENTS.md-canonical repos: When creating new domain context files, create both

AGENTS.md

(with content) and

CLAUDE.md

(companion pointer).

对于每一项重要变更，确定对应的上下文文件：

变更位置	上下文文件位置
项目范围的模式	根目录上下文文件
新增领域	`<domain>/` 上下文文件（创建）
现有领域契约变更	`<domain>/` 上下文文件（更新）
跨领域依赖变更	两个受影响领域的上下文文件

层级规则： 信息应放在其适用的最低层级。领域特定契约应放在领域文件中，而非根目录文件。

对于AGENTS.md标准格式仓库： 创建新领域上下文文件时，需同时创建

AGENTS.md

（包含内容）和

CLAUDE.md

（配套文件）。

Step 3: Verify Contracts Still Hold

步骤3：验证契约是否仍然有效

For each affected context file, verify:

Contracts section: Do exposes/guarantees/expects match current code?
Dependencies section: Are uses/used-by/boundary accurate?
Invariants section: Are all invariants still enforced?
Key Decisions section: Any new decisions to document?

bash

undefined

对于每个受影响的上下文文件，验证：

Contracts部分： 暴露的内容、保证条款、预期是否与当前代码匹配？
Dependencies部分： 使用的依赖、被依赖的对象、边界是否准确？
Invariants部分： 所有不变量是否仍被强制执行？
Key Decisions部分： 是否有新的决策需要记录？

bash

undefined

Find domain's public exports

查找领域的公共导出

grep -r "export" <domain>/index.ts

Find domain's imports (dependencies)

查找领域的依赖（导入）

grep -r "from '.." <domain>/

undefined

grep -r "from '.." <domain>/

undefined

Step 4: Update or Create Context Files

步骤4：更新或创建上下文文件

For updates:

Read existing file first (especially for AGENTS.md)
Update freshness date via
```
date +%Y-%m-%d
```
Update affected sections
Remove stale content
Verify under token budget (<100 lines for domain files)

For new domains (CLAUDE.md-canonical repos):

Create
```
<domain>/CLAUDE.md
```
using template from writing-claude-md-files
Document purpose, contracts, dependencies, invariants
Set freshness date

For new domains (AGENTS.md-canonical repos):

Create
```
<domain>/AGENTS.md
```
using template from writing-claude-md-files
Document purpose, contracts, dependencies, invariants
Set freshness date

Create companion

<domain>/CLAUDE.md

markdown

Read @./AGENTS.md and treat its contents as if they were in CLAUDE.md

更新操作：

先阅读现有文件（尤其是AGENTS.md）
使用
```
date +%Y-%m-%d
```
更新新鲜度日期
更新受影响的部分
删除过时内容
验证内容在token预算内（领域文件不超过100行）

新增领域（CLAUDE.md标准格式仓库）：

使用writing-claude-md-files提供的模板创建
```
<domain>/CLAUDE.md
```
记录Purpose、Contracts、Dependencies、Invariants
设置新鲜度日期

新增领域（AGENTS.md标准格式仓库）：

使用writing-claude-md-files提供的模板创建
```
<domain>/AGENTS.md
```
记录Purpose、Contracts、Dependencies、Invariants
设置新鲜度日期

创建配套的

<domain>/CLAUDE.md

，内容为：

markdown

Read @./AGENTS.md and treat its contents as if they were in CLAUDE.md

Step 5: Commit Documentation Updates

步骤5：提交文档更新

bash

git add <affected CLAUDE.md files>
git commit -m "docs: update project context for <branch-name>"

bash

git add <affected CLAUDE.md files>
git commit -m "docs: update project context for <branch-name>"

Decision Tree

决策树

Has code changed?
├─ No → Skip (nothing to update)
└─ Yes → Detect format first (AGENTS.md at root?)
    │
    └─ What changed?
        ├─ Only tests/internal details → Skip
        └─ Contracts/APIs/structure → Continue
            │
            ├─ New domain created?
            │   ├─ AGENTS.md repo → Create AGENTS.md + companion CLAUDE.md
            │   └─ CLAUDE.md repo → Create CLAUDE.md
            │
            ├─ Existing domain changed?
            │   └─ Update domain context file (read first!)
            │
            └─ Project-wide pattern changed?
                └─ Update root context file

Has code changed?
├─ No → Skip (nothing to update)
└─ Yes → Detect format first (AGENTS.md at root?)
    │
    └─ What changed?
        ├─ Only tests/internal details → Skip
        └─ Contracts/APIs/structure → Continue
            │
            ├─ New domain created?
            │   ├─ AGENTS.md repo → Create AGENTS.md + companion CLAUDE.md
            │   └─ CLAUDE.md repo → Create CLAUDE.md
            │
            ├─ Existing domain changed?
            │   └─ Update domain context file (read first!)
            │
            └─ Project-wide pattern changed?
                └─ Update root context file

Quick Reference

快速参考

Always update when:

New public exports added
Interface signatures changed
Invariants added/removed
Dependencies changed
Architectural decisions made

Never update for:

Internal refactoring
Bug fixes that don't change contracts
Test file changes
Comment/documentation-only changes

必须更新的场景：

新增公共导出
接口签名变更
不变量新增/移除
依赖变更
做出架构决策

无需更新的场景：

内部重构
未变更契约的Bug修复
测试文件变更
仅注释/文档变更

Common Mistakes

常见错误

Mistake	Fix
Updating for every change	Only update for contract changes
Forgetting freshness date	Always use `date +%Y-%m-%d`
Documenting implementation	Document contracts and intent
Putting domain info in root	Use domain context files for domain contracts
Skipping verification	Read the code, confirm contracts hold
Skipping format detection	Always check for AGENTS.md first
Writing AGENTS.md without reading	Always read existing content before updating
Forgetting companion CLAUDE.md	AGENTS.md repos need both files

错误	修复方案
每次变更都更新	仅在契约变更时更新
忘记更新新鲜度日期	始终使用 `date +%Y-%m-%d`
记录实现细节	记录契约和意图
把领域信息放在根目录文件	领域契约使用领域上下文文件
跳过验证步骤	阅读代码，确认契约有效
跳过格式检测	始终先检查是否存在AGENTS.md
未阅读就更新AGENTS.md	更新前务必先阅读现有内容
忘记创建配套CLAUDE.md	AGENTS.md仓库需要同时存在两个文件

Integration Points

集成点

Called by:

project-claude-librarian agent - Uses this skill to coordinate updates
executing-an-implementation-plan (Step 5b) - After all tasks complete
finishing-a-development-branch (Step 4b) - Before merge/PR

Uses:

writing-claude-md-files - For actual context file creation/updates (works for both CLAUDE.md and AGENTS.md)

被以下调用：

project-claude-librarian agent - 使用此技能协调更新
executing-an-implementation-plan（步骤5b）- 所有任务完成后
finishing-a-development-branch（步骤4b）- 合并/PR前

使用到：

writing-claude-md-files - 用于实际创建/更新上下文文件（适用于CLAUDE.md和AGENTS.md）