gravito-architect

Gravito Architect

Overview

Gravito Architect helps developers transform "AI-assisted generated code" into a "technical architecture fully mastered by developers," with a focus on:

Explaining logic and data flow
Defining clear API interfaces
Revealing potential risks (N+1, Race Condition, memory leaks)
Explaining key design decisions

Workflow

Step 1: Understand the input content

Ask the user to provide the following information:

Core code: The main file path to be analyzed
Interface definitions: Related types.ts or interfaces.ts(if present)
Test cases: Related test files (optional, but helpful for understanding expected behavior)
Analysis scope：
- Full analysis (including all sections)
- Focused analysis (only specific sections, such as: performance, design decisions)

Example question：

為了生成準確的技術規格，請提供：
1. 核心程式碼檔案路徑（如：`packages/atlas/src/QueryBuilder.ts`）
2. 相關的型別定義檔案（如：`packages/atlas/src/types.ts`）
3. 測試檔案路徑（如：`packages/atlas/tests/QueryBuilder.test.ts`）

請問需要完整分析，還是僅關注特定面向（如：效能優化、設計決策）？

Step 2: Read and analyze the code

Use the Read tool to read all related files:

// 依序讀取：
// 1. 核心程式碼
// 2. 型別定義
// 3. 測試案例

Analysis focus：

Identify the main classes/functions and their responsibilities
Trace data flow (input → processing → output)
Check design patterns (such as: Builder, Factory, Proxy)
Check for potential issues (refer to references/analysis-checklist.md）

Step 3: Perform in-depth analysis

Follow references/analysis-checklist.md to perform the mandatory check items:

N+1 query problem: Check for database queries inside loops
Race Condition: Check shared state in asynchronous operations
Memory leaks: Check event listeners, timers, caches
Type safety: Check any usage, generic constraints
Exception handling: Check try-catch coverage
Performance bottlenecks: Check time complexity, nested loops
Security issues: Check input validation, SQL Injection

Important: Each issue must provide:

Specific location (file name:line number)
Impact assessment
Actionable fix suggestions

Step 4: Generate the technical specification document

Generate the document according to the structure of references/output-template.md , including:

Module overview
Technical specifications(API Signature + data flow)
Key design decisions
Performance and scalability
Edge cases and limitations
Follow-up optimization suggestions

Output method：

Dialog box: A brief Executive Summary highlighting key findings
Markdown block: The complete technical specification content, which can be directly copied into the project's /docs Table of Contents

Step 5: Provide Copyable Documentation

Use assets/DOCS_ARCH_template.md as a basis to generate ready-to-use Markdown files:

建議將此文檔儲存為：`docs/architecture/[模組名稱].md`

您可以直接複製以下內容：

\`\`\`markdown
[完整的技術規格內容]
\`\`\`

Output Quality Standards

Principles That Must Be Followed

Language: Use Traditional Chinese (Taiwan) terminology throughout
Code Comments: Comments in sample code should also be in Chinese
Quantitative Data: Performance improvements must include specific data (e.g., "from O(n²) to O(n)")
Specific Recommendations: Avoid vague recommendations (e.g., "strengthen testing"); specify which scenarios to test
Problem Location: Mark the file location for every issue (檔案名稱:行號）

Checklist

Before outputting, confirm:

Did it proactively identify N+1, Race Condition, and memory leaks?
Does every design decision explain the "alternative" and its disadvantages?
Does the performance optimization provide quantitative data?
Do edge cases include "workarounds"?
Are follow-up recommendations divided into short-term, mid-term, and long-term?

References

Detailed Template

Output Structure: Refer to references/output-template.md to view the complete example
Analysis Method: Refer to references/analysis-checklist.md to learn how to identify problems

Copyable Template

Document Template：assets/DOCS_ARCH_template.md provides a blank template

Special Considerations

Specific Requirements for the Gravito Project

Since this skill is designed specifically for the Gravito framework, please pay special attention to:

Atlas ORM：
- Check the performance of the query builder (Eager Loading, N+1 issues)
- Analyze the JOIN strategy for related queries
- Check the transaction isolation level
Luminosity：
- Check parameter validation for HTTP routes
- Analyze the execution order of middleware
- Check the error handling mechanism
Bun Runtime：
- Leverage Bun's native APIs (e.g.,Bun.file(), Bun.write()）
- Check whether Node.js-specific APIs are used by mistake

Example Interaction

User Request

我剛完成 Atlas 的 QueryBuilder 模組，請幫我產出技術規格書。

檔案位置：
- packages/atlas/src/QueryBuilder.ts
- packages/atlas/src/types/QueryTypes.ts
- packages/atlas/tests/QueryBuilder.test.ts