grace-explainer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GRACE — Graph-RAG Anchored Code Engineering

GRACE — Graph-RAG锚定的代码工程

GRACE is a methodology for AI-driven code generation that makes codebases navigable by LLMs. It solves the core problem of AI coding assistants: they generate code but can't reliably navigate, maintain, or evolve it across sessions.

GRACE是一种AI驱动的代码生成方法论，它使代码库能够被LLMs（大语言模型）可靠地导航。它解决了AI代码助手的核心问题：这些助手可以生成代码，但无法在不同会话之间可靠地导航、维护或演进代码库。

The Problem GRACE Solves

GRACE解决的问题

LLMs lose context between sessions. Without structure:

They don't know what modules exist or how they connect
They generate code that duplicates or contradicts existing code
They can't trace bugs through the codebase
They drift from the original architecture over time

GRACE provides three interlocking systems that fix this:

Knowledge Graph (docs/knowledge-graph.xml)
    ↓ maps modules, dependencies, exports
Module Contracts (MODULE_CONTRACT in each file)
    ↓ defines WHAT each module does
Semantic Markup (START_BLOCK / END_BLOCK in code)
    ↓ makes code navigable at ~500 token granularity

LLMs在不同会话之间会丢失上下文。如果没有结构化体系：

它们不知道现有哪些模块，以及模块之间如何关联
生成的代码会重复或与现有代码冲突
无法在代码库中追踪bug
随着时间推移，代码会偏离原始架构

GRACE提供了三个相互关联的系统来解决这些问题：

Knowledge Graph (docs/knowledge-graph.xml)
    ↓ maps modules, dependencies, exports
Module Contracts (MODULE_CONTRACT in each file)
    ↓ defines WHAT each module does
Semantic Markup (START_BLOCK / END_BLOCK in code)
    ↓ makes code navigable at ~500 token granularity

Five Core Principles

五大核心原则

1. Never Write Code Without a Contract

1. 无契约不编码

Before generating any module, create its MODULE_CONTRACT with PURPOSE, SCOPE, INPUTS, OUTPUTS. The contract is the source of truth — code implements the contract, not the other way around.

在生成任何模块之前，先创建包含PURPOSE（目标）、SCOPE（范围）、INPUTS（输入）、OUTPUTS（输出）的MODULE_CONTRACT。契约是唯一的事实来源——代码是契约的实现，而非相反。

2. Semantic Markup Is Not Comments

2. 语义标记不是注释

Markers like

// START_BLOCK_<NAME>

and

// END_BLOCK_<NAME>

are navigation anchors, not documentation. They serve as attention anchors for LLM context management and retrieval points for RAG systems.

像

// START_BLOCK_<NAME>

和

// END_BLOCK_<NAME>

这样的标记是导航锚点，而非文档。它们作为LLM上下文管理的注意力锚点，同时也是RAG系统的检索点。

3. Knowledge Graph Is Always Current

3. 知识图谱始终保持最新

docs/knowledge-graph.xml

is the single map of the entire project. When you add a module — add it to the graph. When you add a dependency — add a CrossLink. The graph never drifts from reality.

docs/knowledge-graph.xml

是整个项目的唯一映射。当你添加一个模块时，将其加入图谱；当你添加依赖时，添加CrossLink。图谱永远不会与实际代码脱节。

4. Top-Down Synthesis

4. 自上而下的合成

Code generation follows a strict pipeline:

Requirements → Technology → Development Plan → Module Contracts → Code

Never jump to code. If requirements are unclear — stop and clarify.

代码生成遵循严格的流程：

Requirements → Technology → Development Plan → Module Contracts → Code

绝不要直接跳到编码环节。如果需求不明确，请先停下来澄清。

5. Governed Autonomy (PCAM)

5. 受控自主性（PCAM）

Purpose: defined by the contract (WHAT to build)
Constraints: defined by the development plan (BOUNDARIES)
Autonomy: you choose HOW to implement
Metrics: the contract's outputs tell you if you're done

You have freedom in HOW, not in WHAT. If a contract seems wrong — propose a change, don't silently deviate.

Purpose（目标）：由契约定义（要构建什么）
Constraints（约束）：由开发计划定义（边界范围）
Autonomy（自主性）：由你选择实现方式
Metrics（衡量标准）：契约中的输出定义了完成标准

你可以自由选择实现方式，但不能偏离目标。如果契约存在问题，请提出修改建议，不要擅自偏离。

How the Elements Connect

各组件的关联方式

docs/requirements.xml          — WHAT the user needs (use cases, AAG notation)
        ↓
docs/technology.xml            — WHAT tools we use (runtime, language, versions)
        ↓
docs/development-plan.xml      — HOW we structure it (modules, phases, contracts)
        ↓
docs/knowledge-graph.xml       — MAP of everything (modules, dependencies, exports)
        ↓
src/**/*                       — CODE with GRACE markup (contracts, blocks, maps)

Each layer feeds the next. The knowledge graph is both an output of planning and an input for code generation.

docs/requirements.xml          — WHAT the user needs (use cases, AAG notation)
        ↓
docs/technology.xml            — WHAT tools we use (runtime, language, versions)
        ↓
docs/development-plan.xml      — HOW we structure it (modules, phases, contracts)
        ↓
docs/knowledge-graph.xml       — MAP of everything (modules, dependencies, exports)
        ↓
src/**/*                       — CODE with GRACE markup (contracts, blocks, maps)

每一层都为下一层提供输入。知识图谱既是规划阶段的输出，也是代码生成阶段的输入。

Development Workflow

开发工作流

```
/grace:init
```
— create docs/ structure and CLAUDE.md
Fill in
```
requirements.xml
```
with use cases
Fill in
```
technology.xml
```
with stack decisions
```
/grace:plan
```
— architect modules, generate development plan and knowledge graph
```
/grace:generate <module>
```
— generate one module with full markup
```
/grace:execute
```
— generate all modules with review and commits
```
/grace:refresh
```
— sync knowledge graph after manual changes
```
/grace:fix <error>
```
— debug via semantic navigation
```
/grace:status
```
— health report

```
/grace:init
```
— 创建docs/目录结构和CLAUDE.md文件
在
```
requirements.xml
```
中填写用例
在
```
technology.xml
```
中填写技术栈决策
```
/grace:plan
```
— 设计模块架构，生成开发计划和知识图谱
```
/grace:generate <module>
```
— 生成带有完整标记的单个模块
```
/grace:execute
```
— 生成所有模块，并进行审核和提交
```
/grace:refresh
```
— 手动修改后同步知识图谱
```
/grace:fix <error>
```
— 通过语义导航调试问题
```
/grace:status
```
— 生成健康报告

Detailed References

详细参考文档

For in-depth documentation on each GRACE component, see the reference files in this skill's

references/

directory:

```
references/semantic-markup.md
```
— Block conventions, granularity rules, logging
```
references/knowledge-graph.md
```
— Graph structure, module types, CrossLinks, maintenance
```
references/contract-driven-dev.md
```
— MODULE_CONTRACT, function contracts, PCAM
```
references/unique-tag-convention.md
```
— Unique ID-based XML tags, why they work, full naming table

如需了解GRACE各组件的深入文档，请查看本skill的

references/

目录下的参考文件：

```
references/semantic-markup.md
```
— 块约定、粒度规则、日志记录
```
references/knowledge-graph.md
```
— 图谱结构、模块类型、CrossLink、维护方法
```
references/contract-driven-dev.md
```
— MODULE_CONTRACT、函数契约、PCAM
```
references/unique-tag-convention.md
```
— 基于唯一ID的XML标签、设计原理、完整命名表