organize-ai-context

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Organize AI Context

组织AI上下文

Overview

概述

Use this skill to help any repo organize its AI agent context into standard files:

CLAUDE.md

AGENTS.md

, and

docs/

files (like

ARCHITECTURE.md

TESTING.md

, and

DEVELOPMENT.md

This skill can be used to either setup a new repository or groom an existing one to realign its project context. Run this periodically to continually align and improve the context—much like weeding a garden.

使用本技能可帮助任意仓库将其AI Agent上下文整理为标准文件：

CLAUDE.md

、

AGENTS.md

以及

docs/

目录下的文件（如

ARCHITECTURE.md

、

TESTING.md

和

DEVELOPMENT.md

）。

本技能既可用于搭建新仓库，也可用于梳理现有仓库以重新对齐项目上下文。建议定期运行，持续对齐和优化上下文——就像给花园除草一样。

Mandatory Step: Task Management

强制步骤：任务管理

Before taking action, you MUST check if the repository uses BEADS by running the command

bd prime

If the repository uses BEADS: You MUST use the
```
bd
```
issue tracker for all task management. Do NOT use
```
todowrite
```
or custom markdown files. Claim, create, and close issues using
```
bd
```
as documented in
```
bd prime
```
.
If the repository does NOT use BEADS: You MUST use the
```
todowrite
```
tool (or a local markdown file/task tracker if
```
todowrite
```
is unavailable) to create a clear checklist of planned work before taking action.

执行任何操作前，你必须先运行命令

bd prime

检查仓库是否使用 BEADS。

如果仓库使用 BEADS：所有任务管理必须使用
```
bd
```
议题追踪器。不得使用
```
todowrite
```
或自定义 markdown 文件。请按照
```
bd prime
```
中的说明，使用
```
bd
```
认领、创建和关闭议题。
如果仓库未使用 BEADS：执行操作前，必须使用
```
todowrite
```
工具（如果无法使用
```
todowrite
```
，则使用本地 markdown 文件/任务追踪器）创建清晰的工作计划清单。

File Segmentation & Evolution Rule

文件拆分与演化规则

To maintain a clean and highly readable workspace, you MUST adhere to these segmentation rules:

Never Combine Files: Do NOT combine architecture, development guidelines, testing rules, or security policies into a single file or into the root
```
CLAUDE.md
```
. They MUST live separately under the
```
docs/
```
directory.
Standard Initial State: Every repository must start with the separate individual files listed in the Quick Reference Table below.
Grooming & Evolution: As these documents grow in size and complexity, do not allow them to become sprawling or unreadable:
- When any
```
docs/*.md
```
  file exceeds ~200–300 lines, refactor it into an index / pointer file.
- Move the detailed subsections into a dedicated sub-directory (e.g.,
```
docs/development/style_guide.md
```
  ,
```
docs/development/error_handling.md
```
  ).
- Replace the parent file (e.g.,
```
docs/DEVELOPMENT.md
```
  ) with a high-level summary and links/pointers to the modular sub-files.

为保持工作区整洁且高可读性，你必须遵守以下拆分规则：

禁止合并文件：不得将架构、开发规范、测试规则或安全策略合并到单个文件中，也不得放入根目录的
```
CLAUDE.md
```
中。这些内容必须独立存放在
```
docs/
```
目录下。
标准初始状态：每个仓库都必须从下表快速参考中列出的独立文件开始搭建。
梳理与演化：随着这些文档的篇幅和复杂度增加，请勿让它们变得冗长杂乱或难以阅读：
- 当任意
```
docs/*.md
```
  文件超过约 200–300 行时，将其重构为索引/指引文件。
- 将详细的子章节移动到专门的子目录中（例如
```
docs/development/style_guide.md
```
  、
```
docs/development/error_handling.md
```
  ）。
- 用高层摘要和指向模块化子文件的链接/指引替换父文件（例如
```
docs/DEVELOPMENT.md
```
  ）。

File Evolution Flowchart

文件演化流程图

dot

digraph file_evolution {
    node [shape=box, style=rounded, fontname="Arial", fontsize=10];
    edge [fontname="Arial", fontsize=9];

    "Scan repository state" -> "Are standard docs separate?" [label="Start"];
    "Are standard docs separate?" -> "Create standard files separately" [label="No"];
    "Are standard docs separate?" -> "Check file size / complexity" [label="Yes"];
    
    "Check file size / complexity" -> "Any doc > ~200 lines?" [label="Grooming"];
    "Any doc > ~200 lines?" -> "Keep as separate, single file" [label="No"];
    "Any doc > ~200 lines?" -> "Split: create sub-directory &\nreplace main file with index" [label="Yes"];
}

dot

digraph file_evolution {
    node [shape=box, style=rounded, fontname="Arial", fontsize=10];
    edge [fontname="Arial", fontsize=9];

    "Scan repository state" -> "Are standard docs separate?" [label="Start"];
    "Are standard docs separate?" -> "Create standard files separately" [label="No"];
    "Are standard docs separate?" -> "Check file size / complexity" [label="Yes"];
    
    "Check file size / complexity" -> "Any doc > ~200 lines?" [label="Grooming"];
    "Any doc > ~200 lines?" -> "Keep as separate, single file" [label="No"];
    "Any doc > ~200 lines?" -> "Split: create sub-directory &\nreplace main file with index" [label="Yes"];
}

Quick Reference: Context Blueprint

快速参考：上下文蓝图

File Path	Theme Statement (Required at Top)	Purpose & Key Contents	Evolution Rule
`CLAUDE.md`	Global rules, command reference, and index to all project context — the only file AI agents need to open first	Tech stack, build/test commands, CRITICAL Rules, links to docs.	Stays in root; keeps concise (<100 lines).
`AGENTS.md`	Read-only pointer to CLAUDE.md — its only purpose is to redirect to CLAUDE.md and nothing else	Redirects other agents to read `CLAUDE.md` first.	Stays in root; never modified except to point to `CLAUDE.md` .
`docs/ARCHITECTURE.md`	What is this system? — components, data flow, DB schema, external APIs, and directory layout	Deep architecture, components, data flows, database schemas.	Split into `/docs/architecture/*` if size > 300 lines.
`docs/DEVELOPMENT.md`	How do we write code here? — naming conventions, design principles, error handling, reliability strategy, and planned stack	Coding conventions, patterns, naming, design constraints.	Split into `/docs/development/*` if size > 300 lines.
`docs/PRODUCT.md`	What are we building and why? — user story, requirements, success criteria, and business domain context helpful for understanding why features are built the way they are	Requirements, user stories, success criteria, product vision.	Split into `/docs/product/*` if size > 300 lines.
`docs/SECURITY.md`	How do we keep secrets safe? — environment variables, API key policy, and auth posture	Environment variables, API key policies, auth posture.	Split into `/docs/security/*` if size > 300 lines.
`docs/TESTING.md`	How do we test and fix bugs? — testing requirements, test running instructions, and bug fix policies.	Test suite details, execution steps, CI config, bug fix TDD policy.	Split into `/docs/testing/*` if size > 300 lines.

文件路径	主题说明（顶部必填）	用途与核心内容	演化规则
`CLAUDE.md`	全局规则、命令参考以及所有项目上下文的索引——是AI Agent唯一需要首先打开的文件	技术栈、构建/测试命令、CRITICAL 规则、文档链接。	保留在根目录；保持简洁（<100 行）。
`AGENTS.md`	指向 CLAUDE.md 的只读指引——其唯一用途是重定向到 CLAUDE.md，别无其他	引导其他Agent优先阅读 `CLAUDE.md` 。	保留在根目录；除了指向 `CLAUDE.md` 之外，不得修改。
`docs/ARCHITECTURE.md`	本系统是什么？——组件、数据流、数据库 schema、外部 API 以及目录结构	深度架构、组件、数据流、数据库 schema。	如果篇幅 > 300 行，拆分为 `/docs/architecture/*` 目录。
`docs/DEVELOPMENT.md`	我们如何编写代码？——命名规范、设计原则、错误处理、可靠性策略以及计划使用的技术栈	编码规范、模式、命名、设计约束。	如果篇幅 > 300 行，拆分为 `/docs/development/*` 目录。
`docs/PRODUCT.md`	我们在构建什么，为什么构建？——用户故事、需求、成功标准，以及有助于理解功能设计初衷的业务领域上下文	需求、用户故事、成功标准、产品愿景。	如果篇幅 > 300 行，拆分为 `/docs/product/*` 目录。
`docs/SECURITY.md`	我们如何保障密钥安全？——环境变量、API 密钥策略以及鉴权体系	环境变量、API 密钥策略、鉴权体系。	如果篇幅 > 300 行，拆分为 `/docs/security/*` 目录。
`docs/TESTING.md`	我们如何测试和修复 Bug？——测试要求、测试运行说明以及 Bug 修复策略。	测试套件详情、执行步骤、CI 配置、Bug 修复 TDD 策略。	如果篇幅 > 300 行，拆分为 `/docs/testing/*` 目录。

1. Scan Phase

1. 扫描阶段

Autonomously scan the repository:

Tech Stack: Use
```
read
```
,
```
glob
```
,
```
bash
```
to analyze root config files (e.g.,
```
package.json
```
,
```
Cargo.toml
```
,
```
requirements.txt
```
).
Testing: Look for test directories (
```
tests/
```
,
```
__tests__/
```
,
```
spec/
```
) to infer the testing framework.
Conventions: Check any existing
```
README.md
```
or
```
docs/
```
for current guidelines.

自主扫描仓库：

技术栈：使用
```
read
```
、
```
glob
```
、
```
bash
```
分析根目录的配置文件（例如
```
package.json
```
、
```
Cargo.toml
```
、
```
requirements.txt
```
）。
测试：查找测试目录（
```
tests/
```
、
```
__tests__/
```
、
```
spec/
```
）以推断测试框架。
规范：检查现有的
```
README.md
```
或
```
docs/
```
目录，了解当前的规范。

2. Interactive Phase

2. 交互阶段

Engage the user to fill in gaps and confirm assumptions using the

question

tool:

Verify the inferred tech stack.
Ask for core architectural entry points and design patterns.
Confirm the bug fix and testing policy (e.g., required CI commands like
```
just test-unit
```
).

使用

question

工具与用户沟通，填补信息空白并确认假设：

验证推断出的技术栈。
询问核心架构入口点和设计模式。
确认 Bug 修复和测试策略（例如所需的 CI 命令，如
```
just test-unit
```
）。

3. Generation Phase

3. 生成阶段

Draft and write the primary context files. All primary context files MUST require the appropriate theme statement at the top to help align current and future content. These files must be kept separate as detailed in the File Segmentation & Evolution Rule.

起草并编写核心上下文文件。所有核心上下文文件的顶部必须包含对应的主题说明，以帮助对齐当前和未来的内容。 这些文件必须按照《文件拆分与演化规则》的要求保持独立。

Enforcing CRITICAL Rules in CLAUDE.md

在 CLAUDE.md 中强制执行 CRITICAL 规则

When generating

CLAUDE.md

, you MUST enforce limiting and curating proper global rules under a SINGLE "CRITICAL Rules" heading. DO NOT create an additional Rules section of any kind.

If a rule is truly global, it goes in "CRITICAL Rules".
If a rule is not global, it MUST go in the appropriate
```
docs/*
```
file (e.g.,
```
docs/DEVELOPMENT.md
```
).

You MUST format the CRITICAL Rules heading exactly as follows:

undefined

生成

CLAUDE.md

时，你必须在唯一的「CRITICAL Rules」标题下整理和管控全局规则。不得创建任何其他形式的规则章节。

如果规则确实是全局的，放入「CRITICAL Rules」中。
如果规则不是全局的，必须放入对应的
```
docs/*
```
文件中（例如
```
docs/DEVELOPMENT.md
```
）。

你必须严格按照以下格式编写 CRITICAL Rules 标题：

undefined

CRITICAL Rules

[!IMPORTANT] The following rules are absolute and must be followed by all development agents:


You must suggest the following best practice rules for the "CRITICAL Rules" section in every repo:
1. **Git commits**: single-line only with `git commit -m "..."`, no heredoc, no Co-Authored-By. Prefer Conventional Commits style.
2. **Bash syntax checking**: use `bashcheck` — never `bash -n`
3. **After making any changes, run tests**: [concisely instruct how to run tests in the repo]
4. **Bug fixes require TDD tests**: see `docs/TESTING.md` for policy
5. **Creating new skills**: use `superpowers:writing-skills` skill

You MUST preserve and merge any existing, user-defined rules in `CLAUDE.md` and NEVER silently drop them.
You MUST also prompt the user to review and suggest additional global rules when appropriate.

[!IMPORTANT] The following rules are absolute and must be followed by all development agents:


你必须为每个仓库的「CRITICAL Rules」章节建议以下最佳实践规则：
1. **Git 提交**：仅使用单行 `git commit -m "..."`，禁止 heredoc，禁止 Co-Authored-By。优先使用 Conventional Commits 风格。
2. **Bash 语法检查**：使用 `bashcheck`——禁止使用 `bash -n`
3. **做出任何更改后运行测试**：[简要说明如何在仓库中运行测试]
4. **Bug 修复需要 TDD 测试**：策略参见 `docs/TESTING.md`
5. **创建新技能**：使用 `superpowers:writing-skills` 技能

你**必须**保留并合并 `CLAUDE.md` 中现有的用户自定义规则，绝不能静默丢弃。
你还必须在适当的时候提示用户审核并建议补充其他全局规则。

Common Mistakes

常见错误

Putting everything in the root CLAUDE.md: Putting detailed architectural diagrams, error-handling conventions, or test scripts in
```
CLAUDE.md
```
instead of separate modular
```
docs/*
```
files.
Combining separate context files: Thinking a repository is "too simple" and combining
```
docs/DEVELOPMENT.md
```
and
```
docs/TESTING.md
```
into one single file, violating the separation requirement.
Silently dropping user rules: Overwriting an existing
```
CLAUDE.md
```
or
```
docs/*
```
file and dropping existing user-defined rules or custom instructions.
Forgetting to check for Beads: Bypassing task tracking or failing to check if the repository uses Beads by running
```
bd prime
```
before executing changes.
Using Beads on non-Beads repositories: Running
```
bd
```
commands or worrying about Beads tasks when the repository does not use it.
Drafting rules without local context: Generating generic rules (e.g., standard Node/Python test commands) that do not match the actual codebase tech stack.

将所有内容都放入根目录的 CLAUDE.md：将详细的架构图、错误处理规范或测试脚本放在
```
CLAUDE.md
```
中，而不是放在独立的模块化
```
docs/*
```
文件里。
合并独立的上下文文件：认为仓库「太简单」，将
```
docs/DEVELOPMENT.md
```
和
```
docs/TESTING.md
```
合并为单个文件，违反了拆分要求。
静默丢弃用户规则：覆盖现有的
```
CLAUDE.md
```
或
```
docs/*
```
文件，丢弃已有的用户自定义规则或定制指令。
忘记检查 Beads：执行更改前，绕过任务追踪，或未通过运行
```
bd prime
```
检查仓库是否使用 Beads。
在非 Beads 仓库上使用 Beads：在未使用 Beads 的仓库中运行
```
bd
```
命令或操心 Beads 任务。
脱离本地上下文起草规则：生成与实际代码库技术栈不匹配的通用规则（例如标准的 Node/Python 测试命令）。

Red Flags - STOP

危险信号 - 立即停止

Any modification to
```
CLAUDE.md
```
or
```
docs/
```
is made before checking for Beads using
```
bd prime
```
(if the repo supports it).
A
```
CLAUDE.md
```
file that exceeds 100 lines or contains architectural design / testing details.
User-defined rules or custom instructions in
```
CLAUDE.md
```
are missing after grooming.
Context files are combined under
```
docs/
```
instead of being kept separate.

在使用
```
bd prime
```
检查 Beads 之前（如果仓库支持），就对
```
CLAUDE.md
```
或
```
docs/
```
进行任何修改。
```
CLAUDE.md
```
文件超过 100 行，或包含架构设计/测试细节。
梳理后，
```
CLAUDE.md
```
中的用户自定义规则或定制指令丢失。
```
docs/
```
下的上下文文件被合并，而非保持独立。

Error Handling

错误处理

If the repository structure is highly non-standard or overly large to scan efficiently, lean more heavily on the interactive questionnaire to gather context rather than attempting error-prone guesses.

如果仓库结构极不标准或体量过大，无法高效扫描，应更多依赖交互式问卷来收集上下文，而非尝试容易出错的猜测。