codebase-teach

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

codebase-teach

Analyzes bounded contexts from the project's source tree, extracts domain knowledge per context, writes
ai-context/features/<context>.md
files, and produces
teach-report.md
with coverage metrics.

Triggers:

/codebase-teach

, teach codebase, extract domain knowledge, update feature docs, analyze bounded contexts

从项目源码树中分析Bounded Contexts，提取每个上下文的领域知识，生成
ai-context/features/<context>.md
文件，并输出包含覆盖度指标的
teach-report.md
文件。

触发指令：

/codebase-teach

、teach codebase、extract domain knowledge、update feature docs、analyze bounded contexts

Purpose

用途

codebase-teach

fills the

ai-context/features/

layer with structured domain knowledge derived from reading source code. It is the deep-read complement to

memory-update

(which records session decisions) and

memory-init

(which scaffolds empty stubs). It MUST only be invoked manually by the user.

codebase-teach

通过读取源码，为

ai-context/features/

目录填充结构化的领域知识。它是

memory-update

（记录会话决策）和

memory-init

（生成空的存根文件）的深度读取补充工具。该工具必须仅由用户手动触发。

Process

执行流程

Step 0 — Load project context (non-blocking)

步骤0 — 加载项目上下文（非阻塞）

This step is non-blocking: any failure (missing file, unreadable file) MUST produce at most an INFO-level note. This step MUST NOT produce

status: blocked

status: failed

Read
```
ai-context/stack.md
```
— tech stack, versions, key tools.
Read
```
ai-context/architecture.md
```
— architectural decisions and rationale.
Read
```
ai-context/conventions.md
```
— naming patterns, code conventions.
Read the project's
```
CLAUDE.md
```
(at project root) and extract the
```
## Skills Registry
```
section.

For each file:

If absent: log

INFO: [filename] not found — proceeding without it.

If present: extract

Last updated:

Last analyzed:

date. If date is older than 30 days: log

NOTE: [filename] last updated [date] — context may be stale. Consider running /memory-update or /project-analyze.

Step 1 — Scan bounded contexts

步骤1 — 扫描Bounded Contexts

Identify bounded context candidates by scanning the project directory tree at depth ≤ 2 under these root directories (in order):

```
src/
```
— subdirectories at depth 1 (e.g.,
```
src/auth/
```
,
```
src/payments/
```
)
```
app/
```
— subdirectories at depth 1
```
features/
```
— subdirectories at depth 1
```
domain/
```
— subdirectories at depth 1
```
ai-context/features/
```
— existing feature file names (each file stem is treated as a context name)

Exclusion rules — skip directories named:

shared

utils

common

lib

types

hooks

components

__tests__

test

tests

node_modules

.git

Cross-reference with existing feature files: Read the

ai-context/features/

directory (if it exists) and list all

.md

files, excluding files whose names begin with

(e.g.,

_template.md

For each detected context candidate, build a record:

{ slug: kebab-case of directory name, dir_path, existing_feature_file: bool }

Slug convention: lowercase the directory name; replace spaces and underscores with hyphens. Example:

UserProfile

→

user-profile

auth_service

→

auth-service

If no context candidates are found:

Log:

"No bounded context directories detected."

Write
```
teach-report.md
```
with a Summary noting "No bounded context directories detected" and a recommendation to run
```
/memory-init
```
first.
Stop here.

If
ai-context/features/
does not exist:

Log:

"INFO: ai-context/features/ not found — feature files will be created if possible."

Note in
```
teach-report.md
```
: "ai-context/features/ was absent at run time. Recommend running /memory-init to scaffold the directory before re-running /codebase-teach."
Continue processing (the skill creates the directory and files as needed).

Output:

context_list = [{ slug, dir_path, existing_feature_file: bool }, ...]

Log each context found:

"Detected context: [slug] — [dir_path] (feature file: [exists|absent])"

通过扫描项目目录树（深度≤2）来识别Bounded Context候选对象，扫描优先级如下：

```
src/
```
目录——深度为1的子目录（例如：
```
src/auth/
```
、
```
src/payments/
```
）
```
app/
```
目录——深度为1的子目录
```
features/
```
目录——深度为1的子目录
```
domain/
```
目录——深度为1的子目录
```
ai-context/features/
```
目录——已存在的feature文件名（每个文件的主干名称作为上下文名称）

排除规则——跳过以下名称的目录：

shared

、

utils

、

common

、

lib

、

types

、

hooks

、

components

、

__tests__

、

test

、

tests

、

node_modules

、

.git

与现有feature文件交叉验证： 读取

ai-context/features/

目录（若存在），列出所有

.md

文件，排除名称以下划线

开头的文件（例如：

_template.md

）。

针对每个检测到的上下文候选对象，构建如下记录：

{ slug: 目录名称的短横线分隔格式, dir_path, existing_feature_file: bool }

Slug命名规范： 将目录名称转为小写；将空格和下划线替换为短横线。示例：

UserProfile

→

user-profile

，

auth_service

→

auth-service

。

未找到上下文候选对象的情况：

记录日志：

"No bounded context directories detected."

生成
```
teach-report.md
```
文件，在摘要部分注明"未检测到Bounded Context目录"，并建议先运行
```
/memory-init
```
指令。
终止流程。

ai-context/features/
目录不存在的情况：

记录日志：

"INFO: ai-context/features/ not found — feature files will be created if possible."

在
```
teach-report.md
```
中注明："运行时未找到ai-context/features/目录。建议先运行/memory-init指令生成目录结构，再重新运行/codebase-teach。"
继续执行流程（工具会根据需要创建目录和文件）。

输出：

context_list = [{ slug, dir_path, existing_feature_file: bool }, ...]

记录每个找到的上下文：

"Detected context: [slug] — [dir_path] (feature file: [exists|absent])"

Step 2 — Read key files per context (sequential)

步骤2 — 按上下文读取核心文件（顺序执行）

Process contexts one at a time. For each context in

context_list

Enumerate implementation files in
```
dir_path
```
(recursive), filtering for file extensions:
```
.ts
```
,
```
.tsx
```
,
```
.js
```
,
```
.jsx
```
,
```
.py
```
,
```
.java
```
,
```
.kt
```
,
```
.rb
```
,
```
.go
```
,
```
.ex
```
,
```
.exs
```
,
```
.cs
```
,
```
.rs
```
,
```
.php
```
,
```
.swift
```
- Prioritize files by recency (most recently modified first)
- Exclude files matching:
```
*.test.*
```
  ,
```
*.spec.*
```
  ,
```
test_*
```
  ,
```
*_test.*
```
  ,
```
*.d.ts
```
  ,
```
*.min.*
```

Apply file cap: read at most

max_files

files. If total enumerated >

max_files

, log:

"[slug]: [total] files found — sampling [max_files] (cap applied)"

For each file to read:
- Attempt to read the file
- If the file is binary or unreadable: skip it; record in
```
skipped_files
```
  with reason
- If readable: extract the following signals:
  - Business rules: explicit conditional constraints (if/when/unless logic that enforces domain rules)
  - Invariants: assertions or validation guards that are always enforced
  - Data model entities: class/struct/interface/type names with their key fields
  - Integration points: imports of external services, APIs, or infrastructure adapters

Accumulate:

context_knowledge = { slug, rules[], invariants[], entities[], integrations[], files_read[], skipped[] }

逐个处理上下文列表中的每个上下文：

枚举实现文件：在
```
dir_path
```
目录下递归枚举文件，筛选以下扩展名的文件：
```
.ts
```
、
```
.tsx
```
、
```
.js
```
、
```
.jsx
```
、
```
.py
```
、
```
.java
```
、
```
.kt
```
、
```
.rb
```
、
```
.go
```
、
```
.ex
```
、
```
.exs
```
、
```
.cs
```
、
```
.rs
```
、
```
.php
```
、
```
.swift
```
- 按文件修改时间排序（最新修改的优先）
- 排除匹配以下模式的文件：
```
*.test.*
```
  、
```
*.spec.*
```
  、
```
test_*
```
  、
```
*_test.*
```
  、
```
*.d.ts
```
  、
```
*.min.*
```
应用文件数量上限：最多读取
```
max_files
```
个文件。若枚举到的文件总数大于
```
max_files
```
，记录日志：
```
"[slug]: [total] files found — sampling [max_files] (cap applied)"
```
读取每个目标文件：
- 尝试读取文件内容
- 若文件为二进制文件或无法读取：跳过该文件，并在
```
skipped_files
```
  中记录原因
- 若文件可读：提取以下信息：
  - 业务规则：明确的条件约束（如if/when/unless逻辑，用于执行领域规则）
  - 不变量：始终生效的断言或验证规则
  - 数据模型实体：类/结构体/接口/类型的名称及其核心字段
  - 集成点：外部服务、API或基础设施适配器的导入信息

收集信息：

context_knowledge = { slug, rules[], invariants[], entities[], integrations[], files_read[], skipped[] }

Step 3 — Write

ai-context/features/<slug>.md

步骤3 — 生成

ai-context/features/<slug>.md

文件

For each context processed in Step 2:

If
ai-context/features/<slug>.md
does not exist (or

ai-context/features/

is absent):

Create the directory if needed
Write a new file using the six-section structure below
All AI-generated sections receive
```
[auto-updated]
```
markers

If
ai-context/features/<slug>.md
already exists:

Read the entire file

Identify

<!-- [auto-updated]: codebase-teach ... -->

...

<!-- [/auto-updated] -->

blocks

Overwrite content only inside
```
[auto-updated]
```
blocks
Preserve byte-for-byte all content outside any
```
[auto-updated]
```
block
If no
```
[auto-updated]
```
block exists for a section, append the section at the end of the file inside a new
```
[auto-updated]
```
block

Six-section feature file structure:

markdown

undefined

针对步骤2中处理的每个上下文：

若
ai-context/features/<slug>.md
文件不存在（或

ai-context/features/

目录不存在）：

若需要则创建目录
使用以下六段式结构生成新文件
所有AI生成的内容需添加
```
[auto-updated]
```
标记

若
ai-context/features/<slug>.md
文件已存在：

读取整个文件内容

识别

<!-- [auto-updated]: codebase-teach ... -->

...

<!-- [/auto-updated] -->

代码块

仅覆盖
```
[auto-updated]
```
代码块内的内容
严格保留
```
[auto-updated]
```
代码块外的所有人工编写内容
若某章节不存在
```
[auto-updated]
```
代码块，则在文件末尾添加该章节，并包裹在新的
```
[auto-updated]
```
代码块内

六段式feature文件结构：

markdown

undefined

[Context Name] — Domain Knowledge

[上下文名称] — 领域知识

Last updated by: codebase-teach Last run: YYYY-MM-DD