analyze-project

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Analyze Project

项目分析

Scan a project and produce or update

docs/TechStack.md

and

docs/ProjectStructure.md

— living documentation that any AI agent session can read to instantly understand the project without re-scanning from scratch.

扫描项目并生成或更新

docs/TechStack.md

和

docs/ProjectStructure.md

——这是一种动态文档，任何AI Agent会话都可以通过读取它快速了解项目，无需从头重新扫描。

When to Use

适用场景

Starting work on a project for the first time
Before any feature work when project docs don't exist yet
Periodically to keep docs current after codebase changes
After major refactors, dependency upgrades, or service additions

When NOT to use:

docs/TechStack.md

and

docs/ProjectStructure.md

exist and no significant structural changes (config files, directories, container configs) have occurred since the last scan.

首次开始项目工作时
项目文档尚未存在，即将开展功能开发前
代码库变更后定期运行以保持文档最新
重大重构、依赖升级或新增服务后

不适用场景：

docs/TechStack.md

和

docs/ProjectStructure.md

已存在，且自上次扫描以来未发生重大结构变更（配置文件、目录、容器配置等）。

Input

输入

A project or workspace root (provided by user or detected from workspace)

项目或工作区根目录（由用户提供或从工作区自动检测）

Output

输出

```
docs/TechStack.md
```
— concise tech stack reference card
```
docs/ProjectStructure.md
```
— operational project map
In monorepos: per-service copies under
```
[service-path]/docs/
```

```
docs/TechStack.md
```
——简洁的技术栈参考卡片
```
docs/ProjectStructure.md
```
——可操作的项目结构图
单仓库场景：在
```
[服务路径]/docs/
```
下生成对应服务的文档副本

The Process

操作流程

Step 1: Check Existing Docs

步骤1：检查现有文档

Check if

docs/TechStack.md

and

docs/ProjectStructure.md

exist at the project root.

If they exist, read them and extract the YAML frontmatter:

yaml

---
generated-by: analyze-project
date: 2024-03-14T12:00:00Z
commit: abc1234
---

If the files exist, hold their contents — you'll compare against fresh scan results later.

检查项目根目录下是否存在

docs/TechStack.md

和

docs/ProjectStructure.md

。

若存在，则读取文件并提取YAML frontmatter内容：

yaml

---
generated-by: analyze-project
date: 2024-03-14T12:00:00Z
commit: abc1234
---

若文件已存在，先保留其内容，后续将与新扫描结果进行对比。

Step 2: Staleness Gate

步骤2：时效性检查

Run

git rev-parse --short HEAD

to get the current commit hash.

If the

commit

field in frontmatter differs from HEAD (it usually will — it records the commit at last scan, not the latest), check what actually changed:

Run

git diff --name-only <frontmatter-commit>..HEAD

to get committed changes, and

git status --short

to get uncommitted changes (staged, unstaged, and untracked files). Combine both lists.

Evaluate whether the changes are significant for project docs:

Significant changes (trigger re-scan): new/removed/renamed config files (
```
package.json
```
,
```
composer.json
```
,
```
docker-compose.yml
```
,
```
Dockerfile
```
,
```
Makefile
```
,
```
*.config.*
```
, etc.), new/removed top-level directories, changes to
```
.devcontainer/
```
, CI config changes, README/INSTALL/SETUP changes
Insignificant changes (skip re-scan): source code changes within existing directories, test changes, asset changes, documentation changes in subdirectories

Decision:

Files don't exist → Proceed to scan.
Files exist, commits match HEAD → Report "Project docs are up to date." and stop.
Files exist, commits differ, only insignificant changes → Report "Project docs are up to date (no structural changes since last scan)." and stop.
Files exist, commits differ, significant changes detected → Report which files changed and proceed to scan.
No commit field in frontmatter → Proceed to scan.

If git is not available, skip this check and always proceed to scan.

执行

git rev-parse --short HEAD

命令获取当前commit哈希值。

若frontmatter中的

commit

字段与HEAD不一致（通常都会不同，因为该字段记录的是上次扫描时的commit，而非最新commit），则检查具体变更内容：

执行

git diff --name-only <frontmatter-commit>..HEAD

获取已提交的变更，执行

git status --short

获取未提交的变更（暂存、未暂存和未跟踪文件），合并两个结果列表。

评估变更是否会影响项目文档：

重大变更（触发重新扫描）：新增/删除/重命名配置文件（
```
package.json
```
、
```
composer.json
```
、
```
docker-compose.yml
```
、
```
Dockerfile
```
、
```
Makefile
```
、
```
*.config.*
```
等）、新增/删除顶级目录、
```
.devcontainer/
```
目录变更、CI配置变更、README/INSTALL/SETUP文档变更
非重大变更（跳过重新扫描）：现有目录内的源代码变更、测试代码变更、资源文件变更、子目录内的文档变更

决策逻辑：

文件不存在 → 继续执行扫描。
文件存在，commit与HEAD一致 → 提示“项目文档已处于最新状态。”并终止流程。
文件存在，commit与HEAD不一致，但仅存在非重大变更 → 提示“项目文档已处于最新状态（自上次扫描以来未发生结构变更）。”并终止流程。
文件存在，commit与HEAD不一致，且检测到重大变更 → 告知用户哪些文件发生变更，然后继续执行扫描。
frontmatter中无
commit
字段 → 继续执行扫描。

若无法使用git，则跳过该检查，直接执行扫描。

Step 3: Ownership Check

步骤3：所有权检查

For each existing file, check the

generated-by

field in YAML frontmatter:

generated-by: analyze-project
present → Skill owns this file. Will update without asking.
File exists but no
generated-by: analyze-project
→ Manually authored. Ask the user before overwriting:

"
docs/TechStack.md
exists but wasn't generated by this skill. Overwrite it? (yes/no)"

If user declines, skip that file and report findings in chat instead.

对于每个已存在的文件，检查YAML frontmatter中的

generated-by

字段：

存在
generated-by: analyze-project
→ 该文件由本技能维护，将直接更新，无需询问。
文件存在但无
generated-by: analyze-project
→ 为手动编写文档，覆盖前需询问用户：

"
docs/TechStack.md
已存在，但并非由本技能生成。是否覆盖该文件？（是/否）"

若用户拒绝覆盖，则跳过该文件，仅在聊天中告知扫描结果。

Step 4: Scan Root

步骤4：扫描根目录

List the project root directory. Read relevant files found:

Config files (reveal tech stack):

package.json

composer.json

Cargo.toml

go.mod

pyproject.toml

Gemfile

build.gradle

pom.xml

, etc.

tsconfig.json

vite.config.*

webpack.config.*

nuxt.config.*

, etc.

Container and dev environment:

```
docker-compose.yml
```
/
```
docker-compose.yaml
```
```
Dockerfile
```
```
.devcontainer/devcontainer.json
```

CI/CD:

```
.github/workflows/*.yml
```
```
.gitlab-ci.yml
```
```
Jenkinsfile
```

Documentation:

```
README.md
```
```
INSTALL.md
```
,
```
SETUP.md
```

Quality tooling:

```
Makefile
```
```
.eslintrc.*
```
,
```
eslint.config.*
```
```
.prettierrc
```

phpunit.xml

vitest.config.*

jest.config.*

pytest.ini

Start from the root listing. If root has enough config files, that's all you need. If root contains only a single folder (e.g., the repo wraps one project in a subdirectory), treat that folder as the effective root and list it instead. If root is unclear, run a quick glob for config files (

**/{*.yml,*.yaml,*.json,*.toml,*.ini,*.md}

) limited to a small number of results — the paths reveal where projects and services live (e.g.,

services/api/package.json

). Then read those directories. Avoid full recursive filesystem scans.

列出项目根目录内容，读取找到的相关文件：

配置文件（用于识别技术栈）：

package.json

、

composer.json

、

Cargo.toml

、

go.mod

、

pyproject.toml

、

Gemfile

、

build.gradle

、

pom.xml

等

tsconfig.json

、

vite.config.*

、

webpack.config.*

、

nuxt.config.*

等

容器与开发环境：

```
docker-compose.yml
```
/
```
docker-compose.yaml
```
```
Dockerfile
```
```
.devcontainer/devcontainer.json
```

CI/CD配置：

```
.github/workflows/*.yml
```
```
.gitlab-ci.yml
```
```
Jenkinsfile
```

文档：

```
README.md
```
```
INSTALL.md
```
、
```
SETUP.md
```

质量工具配置：

```
Makefile
```
```
.eslintrc.*
```
、
```
eslint.config.*
```
```
.prettierrc
```

phpunit.xml

、

vitest.config.*

、

jest.config.*

、

pytest.ini

从根目录列表开始扫描。若根目录包含足够的配置文件，则无需进一步扫描。若根目录仅包含单个文件夹（例如仓库将项目嵌套在子目录中），则将该文件夹视为实际根目录并扫描其内容。若根目录不明确，则快速搜索配置文件（

**/{*.yml,*.yaml,*.json,*.toml,*.ini,*.md}

），限制返回结果数量——路径会揭示项目和服务的位置（例如

services/api/package.json

）。然后扫描这些目录。避免对文件系统进行全递归扫描。

Step 5: Detect Monorepo

步骤5：检测单仓库（Monorepo）

Check for monorepo signals from what was found in Step 4:

Directories named
```
apps/
```
,
```
services/
```
,
```
packages/
```
at root
```
docker-compose.yml
```
defining multiple services with build contexts

Workspace config in

package.json

(

workspaces

field) or

pnpm-workspace.yaml

Multiple
```
Dockerfile
```
references in different subdirectories

If monorepo detected, identify service directories and their names.

根据步骤4的结果，检查是否存在单仓库特征：

根目录下存在
```
apps/
```
、
```
services/
```
、
```
packages/
```
目录
```
docker-compose.yml
```
中定义了多个带有构建上下文的服务

package.json

中的

workspaces

字段或

pnpm-workspace.yaml

中的工作区配置

不同子目录中存在多个
```
Dockerfile
```
引用

若检测到单仓库，则识别服务目录及其名称。

Step 6: Scan Services (monorepo only)

步骤6：扫描服务（仅单仓库场景）

For each service directory identified in Step 5, apply the same root-reading approach:

List the service directory
Read its config files (package.json, composer.json, Dockerfile, etc.)
Read its README.md if present
Note its doc location, dev/lint/test commands

对于步骤5中识别的每个服务目录，应用相同的根目录扫描逻辑：

列出服务目录内容
读取其配置文件（package.json、composer.json、Dockerfile等）
若存在README.md则读取该文件
记录其文档位置、开发/ lint/测试命令

Step 7: Write Docs

步骤7：生成文档

Use the templates from

references/formats.md

Single project:

Write
```
docs/TechStack.md
```
with tech stack reference card
Write
```
docs/ProjectStructure.md
```
with operational project map
```
ProjectStructure.md
```
ends with a "See Also" link to
```
DatabaseStructure.md
```

Monorepo:

Write root
```
docs/TechStack.md
```
with shared stack + per-service summary
Write root
```
docs/ProjectStructure.md
```
with service table and monorepo-level overview

For each service, write

[service-path]/docs/TechStack.md

and

[service-path]/docs/ProjectStructure.md

Create
```
docs/
```
directories if they don't exist

All files get YAML frontmatter with:

```
generated-by: analyze-project
```
```
date:
```
current ISO 8601 datetime
```
commit:
```
current short git commit hash

Announce the saved paths:

"Project docs updated:
docs/TechStack.md
docs/ProjectStructure.md
[per-service paths if monorepo] Commit: [hash]"

使用

references/formats.md

中的模板。

单个项目场景：

生成
```
docs/TechStack.md
```
，包含技术栈参考卡片
生成
```
docs/ProjectStructure.md
```
，包含可操作的项目结构图
```
ProjectStructure.md
```
末尾需添加指向
```
DatabaseStructure.md
```
的“另请参阅”链接

单仓库场景：

生成根目录下的
```
docs/TechStack.md
```
，包含共享技术栈和各服务的摘要信息
生成根目录下的
```
docs/ProjectStructure.md
```
，包含服务列表和单仓库概览

为每个服务生成

[服务路径]/docs/TechStack.md

和

[服务路径]/docs/ProjectStructure.md

若
```
docs/
```
目录不存在则创建

所有生成的文件需包含YAML frontmatter，内容如下：

```
generated-by: analyze-project
```
```
date:
```
当前ISO 8601格式的时间戳
```
commit:
```
当前git短提交哈希值

向用户告知已保存的文件路径：

"项目文档已更新：
docs/TechStack.md
docs/ProjectStructure.md
[单仓库场景下的各服务文档路径] 提交哈希：[hash]"

Common Rationalizations

常见误区澄清

Rationalization	Reality
"The README has all this info"	READMEs describe intent and setup steps. TechStack and ProjectStructure describe current reality in a structured, machine-readable format.
"I can just read package.json"	One config file gives you one piece. These docs synthesize all signals into two quick-read files.
"The project is small, I don't need docs"	Small projects still have a stack, structure, and tooling. Two short files save every future session from re-discovering them.
"Docs will get outdated"	The staleness gate and commit tracking exist specifically to prevent this. Run the skill again.

误区	实际情况
"README中已包含所有信息"	README描述的是项目意图和安装步骤，而TechStack和ProjectStructure文档以结构化、机器可读的格式描述项目当前的实际状态。
"我直接读package.json就够了"	单个配置文件只能提供部分信息，这些文档会整合所有信号，生成两个便于快速阅读的文件。
"项目很小，不需要文档"	小型项目同样有技术栈、结构和工具链，两个简短的文档可以为未来的所有会话节省重新探索的时间。
"文档会过时"	时效性检查和commit追踪机制正是为了防止这种情况发生，只需再次运行本技能即可。

Red Flags

注意事项

Skipping the staleness check and always rewriting (wastes time, loses manual edits)
Deep-scanning the filesystem instead of reading root
Not including YAML frontmatter in output files
Overwriting manually-authored files without asking
Missing the monorepo detection step on a multi-service project
Writing rationale or opinions instead of facts in TechStack.md
Not creating
```
docs/
```
directory before writing

跳过时效性检查并始终重写文档（浪费时间，丢失手动编辑内容）
对文件系统进行深度扫描而非仅读取根目录
生成的文件中未包含YAML frontmatter
未询问用户就覆盖手动编写的文件
在多服务项目中未检测到单仓库
在TechStack.md中写入理由或观点而非事实
生成文档前未创建
```
docs/
```
目录

Verification

验证清单

Before finishing, confirm:

Staleness check performed (or git unavailable noted)
Ownership check performed for existing files
Root directory listing read (not deep-scanned)
Relevant config files read
```
docs/TechStack.md
```
written with frontmatter and concise stack listing
```
docs/ProjectStructure.md
```
written with frontmatter and operational map
```
ProjectStructure.md
```
ends with reference to
```
DatabaseStructure.md
```
If monorepo: services detected and per-service docs written
All generated files have
```
generated-by
```
,
```
date
```
, and
```
commit
```
in frontmatter
Saved paths announced to user

完成前请确认：

已执行时效性检查（或已注明无法使用git）
已对现有文件执行所有权检查
已读取根目录列表（未进行深度扫描）
已读取相关配置文件
已生成带有frontmatter和简洁技术栈列表的
```
docs/TechStack.md
```
已生成带有frontmatter和可操作结构图的
```
docs/ProjectStructure.md
```
```
ProjectStructure.md
```
末尾已添加指向
```
DatabaseStructure.md
```
的引用
若为单仓库场景：已检测到服务并生成对应服务的文档
所有生成的文件的frontmatter中包含
```
generated-by
```
、
```
date
```
和
```
commit
```
字段
已向用户告知已保存的文件路径