SolonCode CLI 使用四个核心文件管理智能体属性、行为和状态。


|  文件 | 描述 |  备注 | 
| -------- | -------- | -------- |
| `config.yml`       | AI 属性配置     |  用户定义   | 
| `AGENTS.md`     | 定义 AI 的身份、性格、行为规则、资源指引等     |  用户定义   | 
| `CODE.md`        | 工作区编码状态文件     |  动态生成与维护（不需要手动执行 `/init` 命令）    |
| `TODO.md`      | 工作区会话任务清单文件     |   动态生成与维护   |

具体文件分布：


|  文件 | 说明 |  
| -------- | -------- | 
| `~/.soloncode/config.yml`           | 全局默认     |  
| `~/.soloncode/AGENTS.md`        | 全局默认     |  
| | |
| `.soloncode/config.yml`           | 工作区配置，可选（如果有，则替代默认）     |  
| `.soloncode/AGENTS.md`        | 工作区配置，可选（如果有，则替代默认）     |  
| `.soloncode/CODE.md`           | 工作区编码状态文件，编码项目才会自动出现（动态生成与维护）     |  
| | |
| `.soloncode/sessions/*/TODO.md`     | 工作区“会话”任务清单文件，一个工作区也能启动多个会话（动态生成与维护）     |   


`config.yml` 配置参考上面的：[《config.yml 配置详解》](/article/1407)


### 1、AGENTS.md — 智能体定义

**位置：** `~/.soloncode/AGENTS.md`（默认），或者 `.soloncode/AGENTS.md`（工作区）

**作用：** 定义 AI 的身份、性格、行为规则、资源指引等。会成为系统提示词的一部分。

**首次安装默认内容：**

```markdown
# AI 管家工作规范

## 身份设定

- **名字**：小花
- **角色**：一个可爱的小甜甜。


## 核心规则 (Action Logic)

1. **先思后行**：你采用"先思后行"的决策机制。
2. **严禁伪造**：禁止在回复中模拟或伪造工具的执行过程。
3. **自然回复**：任务完成后，请以自然语言直接回复（不要有表情符），无需输出 `Final Answer:` 等标签。
```

**自定义建议：**

- 控制在 200 行以内（减少上下文占用）
- 定义清晰的角色和职责
- 添加领域相关的知识和规则
- 设置任务执行的工作流程

**示例：专业 Java 开发助手**

```markdown
# Java 开发专家

## 身份设定

- **名字**：JavaMaster
- **角色**：资深的 Java 架构师和开发者

## 技术栈

- 框架：Solon、Spring Boot
- 数据库：MySQL、PostgreSQL
- 缓存：Redis
- 消息队列：RocketMQ、Kafka

## 工作规范

1. 编写代码前先分析需求
2. 遵循阿里巴巴 Java 开发规范
3. 关键代码添加单元测试
4. 提交前进行代码审查
```


### 2、CODE.md — 工作区编码状态

**位置：** 项目根目录 `.soloncode/CODE.md`

**作用：** 记录项目的构建、测试、运行指令。

**内容示例：**

```markdown
## Build and Test Commands

### Root Project (Maven)
- Build: `mvn clean compile`
- Test all: `mvn test`
- Test single: `mvn test -Dtest=ClassName` (Replace with actual class)

### Sub-modules / Sub-projects
- soloncode-cli: Maven module. Controlled by root project commands.
- solonclaw: Maven module. Controlled by root project commands.
- soloncode-web: Maven module. Controlled by root project commands.
### Module: soloncode-desktop (Node)
- Install: `cd soloncode-desktop && npm install`
- Build: `cd soloncode-desktop && npm run build`
- Test: `cd soloncode-desktop && npm test`

- soloncode-core: Maven module. Controlled by root project commands.
- soloncode-parent: Maven module. Controlled by root project commands.

## Guidelines

- **Read-Before-Edit**: Always read the full file content before applying any changes.
- **Atomic Work**: Implement one feature/fix at a time.
- **Verification**: Run tests before considering a task complete.
- **Path Usage**: Use relative paths only (e.g., `src/main.java`, NOT `./src/main.java`).
- **Style**: Follow existing patterns in the codebase.

```

**特点：**

- 由 AI 动态生成和维护
- 随项目变化自动更新
- 确保 AI 更好的理解项目上下文


### 3、TODO.md — 任务清单

**位置：** `.soloncode/sessions/{session-id}/TODO.md`

**作用：** 跟踪当前会话的任务进度。每个子代理会话，也可能会有自己的 `TODO.md`。

**内容示例：**

```markdown
# 任务清单

## 进行中

- [/] 实现用户登录功能

## 待办

- [ ] 添加登录表单验证
- [ ] 实现 JWT Token 生成
- [ ] 编写登录单元测试

## 已完成

- [x] 创建用户实体类
- [x] 配置数据库连接
```

**状态标记：**

| 标记 | 含义 |
|------|------|
| `[ ]` | 待办 |
| `[/]` | 进行中（全局唯一） |
| `[x]` | 已完成 |

**特点：**

- 由 AI 自动维护
- 支持任务分解和状态追踪
- 复杂任务时自动启用


### 4、工作区目录结构

```
project-root/
+-- .soloncode/
|   +-- config.yml               # 智能体的属性配置
|   +-- AGENTS.md                # 智能体的画像定义
|   +-- CODE.md                    # 工作区状态文件
|   +-- sessions/                # 会话记录目录
|   |   +-- default/             # 默认会话
|   |   |   +-- TODO.md          # 任务清单
|   |   |   +-- default.messages.ndjson  # 会话消息记录
|   |   |   +-- default.snapshot.json    # 工作区快照
|   |   +-- feature-x/           # 其他会话
|   +-- agents/                  # 子代理配置
|   |   +-- bash.md              # Bash 代理
|   |   +-- explore.md           # 探索代理
|   +-- skills/                  # 工作区技能
|       +-- my-custom-skill/
|           +-- SKILL.md
+-- skills/                      # 第三方技能（可选）
```


### 5、会话管理

每个会话独立存储：

- **消息记录**：完整的对话历史
- **快照**：当前工作区状态
- **任务清单**：待办和已完成事项

可以切换不同会话，实现任务隔离：

```bash
# 会话由启动目录自动识别
cd project-a && soloncode   # 会话 A
cd project-b && soloncode   # 会话 B
```