ai-ready

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI-Readiness Analysis

AI就绪度分析

Evaluate repository readiness for AI-assisted development across 8 weighted aspects.

评估代码仓库在AI辅助开发场景下的适配情况，涵盖8个加权维度。

Workflow Checklist

工作流检查清单

Copy and track progress:

AI-Readiness Analysis Progress:
- [ ] Step 1: Discover repository
- [ ] Step 2: Gather user context (Q1-Q4)
- [ ] Step 3: Analyze 8 aspects
- [ ] Step 4: Calculate scores and grade
- [ ] Step 5: Display ASCII dashboard
- [ ] Step 6: Present issues by severity
- [ ] Step 7: Priority survey (Q5-Q9)
- [ ] Step 8: Enter plan mode
- [ ] Step 9: Create phased roadmap
- [ ] Step 10: Generate templates
- [ ] Step 11: Save reports to .aiready/ (confirm HTML generation)
- [ ] Step 12: Ask to open HTML report

复制并跟踪进度：

AI-Readiness Analysis Progress:
- [ ] Step 1: Discover repository
- [ ] Step 2: Gather user context (Q1-Q4)
- [ ] Step 3: Analyze 8 aspects
- [ ] Step 4: Calculate scores and grade
- [ ] Step 5: Display ASCII dashboard
- [ ] Step 6: Present issues by severity
- [ ] Step 7: Priority survey (Q5-Q9)
- [ ] Step 8: Enter plan mode
- [ ] Step 9: Create phased roadmap
- [ ] Step 10: Generate templates
- [ ] Step 11: Save reports to .aiready/ (confirm HTML generation)
- [ ] Step 12: Ask to open HTML report

Step 1: Repository Discovery

步骤1：代码仓库发现

Target: {argument OR cwd}

Discover:

Language/Framework: Check package.json, Cargo.toml, go.mod, pyproject.toml
History: Check
```
.aiready/history/index.json
```
for delta tracking
Agent files: CLAUDE.md, AGENTS.md, .cursorrules, copilot-instructions.md

Target: {argument OR cwd}

发现内容：

语言/框架： 检查package.json、Cargo.toml、go.mod、pyproject.toml文件
历史记录： 检查
```
.aiready/history/index.json
```
以进行增量跟踪
Agent相关文件： CLAUDE.md、AGENTS.md、.cursorrules、copilot-instructions.md

Step 2: Context Gathering

步骤2：上下文收集

Use AskUserQuestion with these 4 questions:

Q	Question	Options
Q1	Rework depth?	Quick Wins / Medium / Deep Refactor
Q2	Timeline?	Urgent / Planned / Strategic / Continuous
Q3	Team size?	Solo / Small (2-5) / Large (5+) / Open Source
Q4	AI tools used?	Claude Code / Copilot / Cursor / Windsurf / Aider (multiselect)

Store responses for Steps 6 and 11.

使用AskUserQuestion工具询问以下4个问题：

序号	问题	选项
Q1	重构深度？	快速优化 / 中等重构 / 深度重构
Q2	时间线？	紧急 / 计划中 / 战略级 / 持续优化
Q3	团队规模？	个人 / 小型团队（2-5人） / 大型团队（5人以上） / 开源项目
Q4	使用的AI工具？	Claude Code / Copilot / Cursor / Windsurf / Aider（可多选）

保存回答结果，用于步骤6和步骤11。

Step 3: Analyze 8 Aspects

步骤3：8个维度分析

Evaluate each criterion 0-5-10. See criteria/aspects.md for full rubrics.

Aspect	Weight	Criteria
Documentation	15%	19
Architecture	15%	18
Testing	12%	23
Type Safety	12%	10
Agent Instructions	15%	25
File Structure	10%	13
Context Optimization	11%	20
Security	10%	12

每个评估项按0-5-10分制打分。完整评分标准请查看**criteria/aspects.md**。

评估维度	权重	评估项数量
文档	15%	19
架构	15%	18
测试	12%	23
类型安全	12%	10
Agent指令	15%	25
文件结构	10%	13
上下文优化	11%	20
安全	10%	12

Step 4: Calculate Scores

步骤4：分数计算

Aspect Score = (Sum of criteria / Max points) × 100

Overall = (Doc × 0.15) + (Arch × 0.15) + (Test × 0.12) + (Type × 0.12)
        + (Agent × 0.15) + (File × 0.10) + (Context × 0.11) + (Security × 0.10)

Grade	Range
A	90-100
B	75-89
C	60-74
D	45-59
F	0-44

Aspect Score = (Sum of criteria / Max points) × 100

Overall = (Doc × 0.15) + (Arch × 0.15) + (Test × 0.12) + (Type × 0.12)
        + (Agent × 0.15) + (File × 0.10) + (Context × 0.11) + (Security × 0.10)

等级	分数范围
A	90-100
B	75-89
C	60-74
D	45-59
F	0-44

Step 5: Display Dashboard

步骤5：展示仪表盘

╔══════════════════════════════════════════════════════════════════════════════╗
║                          AI-READINESS REPORT                                  ║
║  Repository: {name} | Language: {lang} | Framework: {fw}                     ║
╠══════════════════════════════════════════════════════════════════════════════╣
║  OVERALL GRADE: {X}     SCORE: {XX}/100     {delta}                          ║
╠══════════════════════════════════════════════════════════════════════════════╣
║  1. Documentation       {bar} {score}/100 {delta}                            ║
║  2. Architecture        {bar} {score}/100 {delta}                            ║
║  3. Testing             {bar} {score}/100 {delta}                            ║
║  4. Type Safety         {bar} {score}/100 {delta}                            ║
║  5. Agent Instructions  {bar} {score}/100 {delta}                            ║
║  6. File Structure      {bar} {score}/100 {delta}                            ║
║  7. Context Optimization{bar} {score}/100 {delta}                            ║
║  8. Security            {bar} {score}/100 {delta}                            ║
╚══════════════════════════════════════════════════════════════════════════════╝

Progress bars:

████████░░

= 80/100 (█ filled, ░ empty, 10 chars total)

Deltas:

↑+N

improvement |

↓-N

decline |

→0

unchanged |

(new)

first run

Issue Summary Block:

╔══════════════════════════════════════════════════════════════════════════════╗
║                          ISSUE SUMMARY                                        ║
╠══════════════════════════════════════════════════════════════════════════════╣
║   🔴 CRITICAL     {bar}  {N}                                                 ║
║   🟡 WARNING      {bar}  {N}                                                 ║
║   🔵 INFO         {bar}  {N}                                                 ║
║   Distribution by Aspect: (sorted by issue count)                            ║
╚══════════════════════════════════════════════════════════════════════════════╝

If history exists, show Progress Over Time chart with trend analysis.

╔══════════════════════════════════════════════════════════════════════════════╗
║                          AI-READINESS REPORT                                  ║
║  Repository: {name} | Language: {lang} | Framework: {fw}                     ║
╠══════════════════════════════════════════════════════════════════════════════╣
║  OVERALL GRADE: {X}     SCORE: {XX}/100     {delta}                          ║
╠══════════════════════════════════════════════════════════════════════════════╣
║  1. Documentation       {bar} {score}/100 {delta}                            ║
║  2. Architecture        {bar} {score}/100 {delta}                            ║
║  3. Testing             {bar} {score}/100 {delta}                            ║
║  4. Type Safety         {bar} {score}/100 {delta}                            ║
║  5. Agent Instructions  {bar} {score}/100 {delta}                            ║
║  6. File Structure      {bar} {score}/100 {delta}                            ║
║  7. Context Optimization{bar} {score}/100 {delta}                            ║
║  8. Security            {bar} {score}/100 {delta}                            ║
╚══════════════════════════════════════════════════════════════════════════════╝

进度条：

████████░░

= 80/100（█为填充，░为空白，共10个字符）

变化量：

↑+N

提升 |

↓-N

下降 |

→0

无变化 |

(new)

首次运行

问题摘要块：

╔══════════════════════════════════════════════════════════════════════════════╗
║                          ISSUE SUMMARY                                        ║
╠══════════════════════════════════════════════════════════════════════════════╣
║   🔴 CRITICAL     {bar}  {N}                                                 ║
║   🟡 WARNING      {bar}  {N}                                                 ║
║   🔵 INFO         {bar}  {N}                                                 ║
║   Distribution by Aspect: (sorted by issue count)                            ║
╚══════════════════════════════════════════════════════════════════════════════╝

如果存在历史记录，展示随时间变化的进度图表及趋势分析。

Step 6: Present Issues

步骤6：展示问题

Group by severity, then aspect. See reference/severity.md for classification.

🔴 CRITICAL ({N})
──────────────────────────────────────────────────────────────────────
[C1] {Aspect}: {Issue}
     Impact: {description}
     Effort: Low/Medium/High

🟡 WARNING ({N})
──────────────────────────────────────────────────────────────────────
[W1] {Aspect}: {Issue}
     Impact: {description}

按问题严重程度分组，再按评估维度排序。分类标准请查看**reference/severity.md**。

🔴 CRITICAL ({N})
──────────────────────────────────────────────────────────────────────
[C1] {Aspect}: {Issue}
     Impact: {description}
     Effort: Low/Medium/High

🟡 WARNING ({N})
──────────────────────────────────────────────────────────────────────
[W1] {Aspect}: {Issue}
     Impact: {description}

Step 7: Priority Survey

步骤7：优先级调研

Use AskUserQuestion for prioritization:

Q	Question	Purpose
Q5	Priority areas (top 3)?	Focus recommendations
Q6	Critical issue order?	Prioritize fixes
Q7	Which warnings to fix?	Scope work
Q8	Constraints?	Legacy code, compliance, CI/CD
Q9	Success metrics?	Target grade, zero critical

Filter by rework depth from Q1:

Quick Wins → Phase 1 only
Medium → Phases 1-2
Deep → All phases

使用AskUserQuestion工具进行优先级调研：

序号	问题	目的
Q5	优先级最高的3个维度？	聚焦建议方向
Q6	关键问题的处理顺序？	确定修复优先级
Q7	需要修复哪些警告类问题？	界定工作范围
Q8	约束条件？	遗留代码、合规要求、CI/CD限制
Q9	成功指标？	目标等级、零关键问题

根据Q1的重构深度进行过滤：

快速优化 → 仅执行第一阶段
中等重构 → 执行第一、二阶段
深度重构 → 执行所有阶段

Step 8: Enter Plan Mode

步骤8：进入计划模式

After survey, use EnterPlanMode tool.

调研完成后，使用EnterPlanMode工具。

Step 9: Phased Roadmap

步骤9：分阶段路线图

Phase	Focus	Examples
1: Quick Wins	File creation, config	CLAUDE.md, .aiignore, llms.txt
2: Foundation	Structural changes	ARCHITECTURE.md, file splitting, types
3: Advanced	Deep improvements	Coverage >80%, ADRs, architecture enforcement

阶段	聚焦方向	示例
1: 快速优化	文件创建、配置	CLAUDE.md、.aiignore、llms.txt
2: 基础构建	结构调整	ARCHITECTURE.md、文件拆分、类型定义
3: 进阶优化	深度改进	测试覆盖率>80%、架构决策记录（ADRs）、架构规范落地

Step 10: Generate Templates

步骤10：生成模板

For selected issues, generate from templates:

CLAUDE.md: See templates/CLAUDE.md.template
ARCHITECTURE.md: See templates/ARCHITECTURE.md.template

针对选中的问题，从模板生成对应内容：

CLAUDE.md： 请查看**templates/CLAUDE.md.template**
ARCHITECTURE.md： 请查看**templates/ARCHITECTURE.md.template**

Step 11: Save Reports

步骤11：保存报告

Before writing the HTML file, always ask the user:

AskUserQuestion:
  Question: "Generate HTML report now?"
  Options: ["Yes, generate HTML", "No, skip HTML"]

If "Yes", create the HTML report. If "No", skip HTML but still write Markdown/JSON.

Save to

.aiready/history/reports/

with timestamp:

.aiready/
├── config.json              # User preferences
├── history/
│   ├── index.json           # Report index for delta tracking
│   └── reports/
│       ├── {YYYY-MM-DD}_{HHMMSS}.md
│       ├── {YYYY-MM-DD}_{HHMMSS}.html
│       └── {YYYY-MM-DD}_{HHMMSS}.json

Markdown report: Scores, issues, recommendations, user context HTML dashboard: See templates/report.html JSON data: Raw scores for delta tracking

Update

index.json

with new report entry and trend analysis.

在生成HTML文件前，务必询问用户：

AskUserQuestion:
  Question: "现在生成HTML报告吗？"
  Options: ["是，生成HTML报告", "否，跳过HTML报告"]

如果选择“是”，则生成HTML报告；如果选择“否”，则跳过HTML报告，但仍需生成Markdown/JSON格式报告。

保存到

.aiready/history/reports/

目录，文件名包含时间戳：

.aiready/
├── config.json              # User preferences
├── history/
│   ├── index.json           # Report index for delta tracking
│   └── reports/
│       ├── {YYYY-MM-DD}_{HHMMSS}.md
│       ├── {YYYY-MM-DD}_{HHMMSS}.html
│       └── {YYYY-MM-DD}_{HHMMSS}.json

Markdown报告： 包含分数、问题、建议、用户上下文 HTML仪表盘： 请查看**templates/report.html** JSON数据： 原始分数，用于增量跟踪

更新

index.json

，添加新报告条目及趋势分析。

Open Report

打开报告

If the HTML report was generated and saved, immediately ask:

AskUserQuestion:
  Question: "Open HTML report in browser?"
  Options: ["Yes, open report", "No, skip"]

If HTML was skipped, do not prompt to open. If yes, run:

bash

open .aiready/history/reports/{timestamp}.html

如果已生成并保存HTML报告，立即询问用户：

AskUserQuestion:
  Question: "在浏览器中打开HTML报告吗？"
  Options: ["是，打开报告", "否，跳过"]

如果跳过了HTML报告生成，则不弹出此提示。如果选择“是”，执行以下命令：

bash

open .aiready/history/reports/{timestamp}.html

Validation Loop

验证循环

After each major step, verify:

After analysis: All 8 aspects scored?
After issues: Severity correctly classified?
After survey: User selections captured?
After templates: Files properly generated?
After save: Reports written to .aiready/?

If validation fails, return to the failed step.

在每个主要步骤完成后，进行验证：

分析完成后： 8个维度是否都已评分？
问题展示后： 问题严重程度分类是否正确？
调研完成后： 是否已记录用户的选择？
模板生成后： 文件是否正确生成？
保存完成后： 报告是否已写入.aiready/目录？

如果验证失败，返回至失败的步骤。

Quick Reference

快速参考

File	Content
criteria/aspects.md	Full scoring rubrics for all 8 aspects
reference/severity.md	Issue severity classification
templates/CLAUDE.md.template	Agent instructions template
templates/ARCHITECTURE.md.template	Architecture doc template
templates/report.html	HTML dashboard template
examples/	Example reports

文件	内容
criteria/aspects.md	所有8个维度的完整评分标准
reference/severity.md	问题严重程度分类标准
templates/CLAUDE.md.template	Agent指令模板
templates/ARCHITECTURE.md.template	架构文档模板
templates/report.html	HTML仪表盘模板
examples/	示例报告