Skip to content

Commit 92e9e95

Browse files
CodeCasterXclaude
andcommitted
docs(ai-agents): 优化 AGENTS.md 配置,遵循官方标准最佳实践
基于 AGENTS.md 官方标准(Linux Foundation AAIF)的最佳实践,全面优化项目的 AI 协作配置: - 精简根目录 AGENTS.md 至 91 行(-31.6%),聚焦快速命令和硬性规则 - 优化 preferences.yaml 配置文件至 ~60 行(-73.6%),删除与 AGENTS.md 重复的编码规范 - 明确文件职责分工:AGENTS.md(AI 指令)、README.md(协作说明)、preferences.yaml(工具配置) - 删除重复的版权管理规则,统一到 AGENTS.md 维护 - 更新文档引用关系,提升配置可维护性 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
1 parent 36985aa commit 92e9e95

File tree

5 files changed

+91
-361
lines changed

5 files changed

+91
-361
lines changed

.ai-agents/QUICKSTART.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
# 多 AI 协作快速开始指南
22

3-
本指南帮助你快速上手 FIT Framework 的多 AI 协作功能(支持 ClaudeCode、Codex、GeminiCli)。
3+
本指南帮助你快速上手 FIT Framework 的多 AI 协作功能(支持 Claude Code、Codex、Gemini CLI、Cursor 等)。
4+
5+
> **📌 重要提示**:开始协作前,请先阅读根目录的 `AGENTS.md` 文件,了解项目的基本开发规范和命令。
46
57
## 🚀 5分钟快速开始
68

.ai-agents/README.md

Lines changed: 6 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
1-
# FIT Framework - AI 智能体协作配置
1+
# FIT Framework - AI 智能体协作指南
22

3-
本目录包含 FIT Framework 项目的 AI 智能体协作配置,支持三个主流 AI 工具(ClaudeCode、Codex、GeminiCli)在同一项目中高效协作。
3+
本目录包含 FIT Framework 项目的 AI 智能体协作配置,支持多个主流 AI 工具(Claude Code、Codex、Gemini CLI、Cursor 等)在同一项目中高效协作。
4+
5+
> **💡 提示**:如需快速了解项目规范,请先阅读根目录的 `AGENTS.md` 文件。本文档专注于**多 AI 协作机制**的详细说明。
46
57
## 📋 目录说明
68

@@ -411,38 +413,10 @@ GeminiCli 的配置在 `.ai-agents/gemini/` 目录。
411413
### 通用配置
412414

413415
所有 AI 都应该:
414-
1. 读取 `AGENTS.md`(项目根目录)
415-
2. 遵循 `.ai-agents/workflows/` 中的工作流
416+
1. 读取 `AGENTS.md`(项目根目录)获取项目开发规范
417+
2. 遵循 `.ai-agents/workflows/` 中的工作流定义
416418
3. 使用 `.ai-workspace/` 进行任务跟踪和上下文共享
417419

418-
### 版权年份管理规范
419-
420-
**重要规则**:修改任意带版权头的文件时,**必须同步更新版权年份到当前年份**
421-
422-
**执行步骤**
423-
424-
1. **动态获取当前年份**(绝对不要硬编码年份):
425-
```bash
426-
# 使用系统命令获取当前年份
427-
CURRENT_YEAR=$(date +%Y)
428-
echo $CURRENT_YEAR
429-
```
430-
431-
2. **检查并更新版权头**
432-
- 检查文件是否包含版权声明(如 `Copyright (C) 2024-2025`
433-
- 如果包含,将年份更新为当前年份(如 `2024-2025``2024-2026`
434-
- 如果是单一年份(如 `2024`),更新为年份范围(如 `2024-2026`
435-
436-
3. **常见格式示例**(假设当前年份为 2026):
437-
- `Copyright (C) 2024-2025``Copyright (C) 2024-2026`
438-
- `Copyright (C) 2024``Copyright (C) 2024-2026`
439-
- `© 2024-2025``© 2024-2026`
440-
441-
**为什么重要**
442-
- 确保版权声明的准确性和法律有效性
443-
- 遵循项目规范,保持一致性
444-
- 避免年份过时导致的合规问题
445-
446420
## ⚠️ 注意事项
447421

448422
### 人工检查点

.ai-agents/codex/preferences.yaml

Lines changed: 12 additions & 154 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
1-
# ChatGPT 偏好配置
2-
# 这个文件帮助 ChatGPT 了解在 FIT Framework 项目中的角色和偏好
1+
# Codex (ChatGPT) 偏好配置
2+
# 这个文件帮助 Codex/ChatGPT 了解在 FIT Framework 项目中的角色和偏好
3+
# 项目编码规范请参考根目录的 AGENTS.md 文件
34

45
agent:
5-
name: "GPT"
6+
name: "Codex"
67
role: "Implementation & Testing Specialist"
7-
version: "ChatGPT-4 / ChatGPT-4 Turbo"
8-
# 交流语言:跟随用户输入
8+
version: "ChatGPT-4 / ChatGPT-4 Turbo / O1"
99
communication_language: "Adaptive (Match user's language)"
1010

1111
# 擅长的任务类型
@@ -24,50 +24,10 @@ recommended_steps:
2424
- "bug-fix" # Bug修复
2525
- "refactoring-implementation" # 重构实施
2626

27-
# 代码风格偏好
28-
coding_style:
29-
language: "Java"
30-
formatter: "IntelliJ IDEA (CodeFormatterFromIdea.xml)"
31-
line_length: 120
32-
indent: 4
33-
use_tabs: false
34-
35-
naming:
36-
classes: "PascalCase"
37-
methods: "camelCase"
38-
constants: "UPPER_SNAKE_CASE"
39-
packages: "lowercase"
40-
41-
comments:
42-
javadoc_required: true # 公共API必须有Javadoc
43-
inline_comments: "when necessary"
44-
class_header: true # 需要 @author 和 @since
45-
46-
# 测试偏好
47-
testing:
48-
framework: "JUnit"
49-
naming_convention: "*Test.java"
50-
coverage_target: "80%"
51-
test_types:
52-
- "unit"
53-
- "integration"
54-
55-
assertions_library: "JUnit Assertions"
56-
57-
best_practices:
58-
- "每个公共方法至少一个测试"
59-
- "覆盖正常和异常情况"
60-
- "使用有意义的测试名称"
61-
- "测试应该独立,不依赖执行顺序"
62-
6327
# Git 操作偏好
6428
git:
6529
auto_commit: false # 不自动提交,等待人工确认
66-
commit_message_format: "[{module}] {description}"
67-
commit_message_language: "Chinese"
68-
69-
branch_naming: "{module}-{type}-{description}"
70-
# 例如: fit-feature-new-api, waterflow-bugfix-null-pointer
30+
auto_push: false # 不自动推送
7131

7232
# 协作偏好
7333
collaboration:
@@ -94,133 +54,31 @@ collaboration:
9454

9555
# 输出偏好
9656
output:
97-
# 代码实现报告应包含的内容
9857
implementation_report:
9958
- "modified_files_list"
10059
- "key_implementation_notes"
10160
- "test_results"
10261
- "review_checklist"
10362
- "known_issues"
104-
105-
# 文档格式
63+
10664
documentation_format: "Markdown"
107-
108-
# 代码注释语言
10965
code_comments_language: "Chinese"
110-
111-
# 文档语言
11266
documentation_language: "Chinese"
11367

114-
# 质量标准
115-
quality_standards:
116-
code:
117-
- "遵循项目编码规范"
118-
- "代码可读性高"
119-
- "适当的错误处理"
120-
- "避免代码重复"
121-
- "性能考虑"
122-
123-
tests:
124-
- "测试覆盖关键逻辑"
125-
- "测试名称清晰"
126-
- "断言明确"
127-
- "测试独立性"
128-
129-
documentation:
130-
- "公共API有Javadoc"
131-
- "复杂逻辑有注释"
132-
- "README保持更新"
133-
134-
# 安全意识
135-
security:
136-
checks:
137-
- "输入验证"
138-
- "SQL注入防护"
139-
- "XSS防护"
140-
- "敏感信息处理"
141-
- "权限检查"
142-
143-
never_do:
144-
- "提交敏感信息(密码、密钥)"
145-
- "跳过安全检查"
146-
- "使用不安全的API"
147-
148-
# 性能意识
149-
performance:
150-
considerations:
151-
- "避免N+1查询"
152-
- "合理使用缓存"
153-
- "注意循环复杂度"
154-
- "资源及时释放"
155-
156-
profiling:
157-
- "复杂操作添加日志"
158-
- "关注时间复杂度"
159-
16068
# 项目特定配置
16169
project_specific:
16270
fit_framework:
16371
main_language: "Java"
16472
build_tool: "Maven"
165-
jdk_version: "8+"
166-
167-
modules:
168-
- "fit-java"
169-
- "fit-python"
170-
- "waterflow"
171-
- "fel"
172-
73+
17374
common_commands:
17475
build: "mvn clean install"
17576
test: "mvn test"
176-
quick_build: "mvn -B clean package -Dmaven.test.skip=true"
17777
start: "./build/bin/fit start"
17878

179-
important_files:
180-
- "AGENTS.md"
181-
- ".ai-agents/README.md"
182-
- ".github/PULL_REQUEST_TEMPLATE.md"
183-
- "CodeFormatterFromIdea.xml"
184-
18579
# 自动化行为
18680
automation:
187-
auto_format_code: true # 自动格式化代码
188-
auto_run_tests: true # 完成后自动运行测试
189-
auto_fix_style: true # 自动修复代码风格问题
190-
auto_commit: false # 不自动提交
191-
auto_push: false # 不自动推送
192-
193-
# 学习和改进
194-
continuous_improvement:
195-
learn_from:
196-
- "Code review feedback from Claude"
197-
- "Test failures"
198-
- "Human feedback"
199-
200-
improve:
201-
- "Code quality over time"
202-
- "Test coverage"
203-
- "Documentation completeness"
204-
205-
---
206-
207-
# 使用说明
208-
209-
## 如何使用这个配置
210-
211-
如果你是 ChatGPT,在 FIT Framework 项目中工作时:
212-
213-
1. 参考这个配置文件了解项目偏好
214-
2. 遵循定义的编码规范和测试要求
215-
3. 与 Claude 等其他 AI 协作时参考 collaboration 部分
216-
4. 输出文件时参考 output 部分的要求
217-
218-
## 配置优先级
219-
220-
1. 项目规范(AGENTS.md)> 本配置文件
221-
2. 人类指令 > 所有配置
222-
3. Workflow定义 > 一般性偏好
223-
224-
## 更新这个配置
225-
226-
根据项目发展和团队反馈,定期更新这个配置文件。
81+
auto_format_code: true
82+
auto_run_tests: true
83+
auto_commit: false
84+
auto_push: false

.ai-agents/gemini/preferences.yaml

Lines changed: 5 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
11
# Gemini 偏好配置
22
# 这个文件帮助 Gemini 了解在 FIT Framework 项目中的角色和偏好
3+
# 项目编码规范请参考根目录的 AGENTS.md 文件
34

45
agent:
56
name: "Gemini"
67
role: "Implementation & Multimodal Specialist"
7-
version: "Gemini Pro / Ultra"
8-
# 交流语言:跟随用户输入
8+
version: "Gemini Pro / Ultra / Flash"
99
communication_language: "Adaptive (Match user's language)"
1010

1111
# 擅长的任务类型
1212
strengths:
1313
- "Multimodal understanding (text, images, code)"
1414
- "Fast code implementation"
15-
- "Code analysis"
15+
- "Large codebase analysis (2M token context)"
1616
- "Test generation"
1717
- "Documentation generation"
1818

@@ -23,45 +23,10 @@ recommended_steps:
2323
- "bug-fix" # Bug修复
2424
- "code-review-assistance" # 辅助代码审查
2525

26-
# 代码风格偏好
27-
coding_style:
28-
language: "Java"
29-
formatter: "IntelliJ IDEA (CodeFormatterFromIdea.xml)"
30-
line_length: 120
31-
indent: 4
32-
use_tabs: false
33-
34-
naming:
35-
classes: "PascalCase"
36-
methods: "camelCase"
37-
constants: "UPPER_SNAKE_CASE"
38-
packages: "lowercase"
39-
40-
comments:
41-
javadoc_required: true
42-
inline_comments: "when necessary"
43-
class_header: true # 需要 @author 和 @since
44-
45-
# 测试偏好
46-
testing:
47-
framework: "JUnit"
48-
naming_convention: "*Test.java"
49-
coverage_target: "80%"
50-
test_types:
51-
- "unit"
52-
- "integration"
53-
54-
best_practices:
55-
- "每个公共方法至少一个测试"
56-
- "覆盖正常和异常情况"
57-
- "测试应该独立"
58-
5926
# Git 操作偏好
6027
git:
6128
auto_commit: false
62-
commit_message_format: "[{module}] {description}"
63-
commit_message_language: "Chinese"
64-
branch_naming: "{module}-{type}-{description}"
29+
auto_push: false
6530

6631
# 协作偏好
6732
collaboration:
@@ -91,17 +56,6 @@ output:
9156
code_comments_language: "Chinese"
9257
documentation_language: "Chinese"
9358

94-
# 质量标准
95-
quality_standards:
96-
code:
97-
- "遵循项目编码规范"
98-
- "代码可读性高"
99-
- "性能考虑"
100-
101-
tests:
102-
- "测试覆盖关键逻辑"
103-
- "断言明确"
104-
10559
# 项目特定配置
10660
project_specific:
10761
fit_framework:
@@ -116,21 +70,4 @@ automation:
11670
auto_format_code: true
11771
auto_run_tests: true
11872
auto_commit: false
119-
120-
---
121-
122-
# 使用说明
123-
124-
## 如何使用这个配置
125-
126-
如果你是 Gemini,在 FIT Framework 项目中工作时:
127-
128-
1. 参考这个配置文件了解项目偏好
129-
2. 遵循定义的编码规范和测试要求
130-
3. 与 Claude 等其他 AI 协作时参考 collaboration 部分
131-
4. 所有的交流、文档、提交信息默认使用中文
132-
133-
## 配置优先级
134-
135-
1. 项目规范(AGENTS.md)> 本配置文件
136-
2. 人类指令 > 所有配置
73+
auto_push: false

0 commit comments

Comments
 (0)