Agent Skills
› NeverSight/learn-skills.dev
› nodejs-project-arch
nodejs-project-arch
GitHub为AI辅助开发制定Node.js架构规范，强制文件拆分（<400行）和配置外部化，以节省上下文窗口。涵盖H5游戏、数据工具、API服务等类型，提供模块化结构及Admin后台热更新配置方案。
Trigger Scenarios
创建新的Node.js项目
重构大型单文件代码库
AI上下文窗口被大文件占用时
Install
npx skills add NeverSight/learn-skills.dev --skill nodejs-project-arch -g -y
SKILL.md
Frontmatter
{
"name": "nodejs-project-arch",
"description": "Node.js project architecture standards for AI-assisted development. Enforces file splitting (<400 lines), config externalization, route modularization, and admin dashboards. Use when creating new Node.js projects, refactoring large single-file codebases, or when AI context window is being consumed by oversized files. Covers H5 games (Canvas\/Phaser\/Matter.js), data tools (crawlers\/scrapers), content platforms, monitoring dashboards, API services, and SDK libraries."
}
Node.js Project Architecture for AI-Friendly Development
Architecture standards that keep files small enough for AI agents to read/edit without blowing the context window.
Core Rules
- Single file max 400 lines,
index.htmlmax 200 lines,server.jsentry max 100 lines - All tunable values in
config.json, loaded at runtime, editable via admin dashboard - Backend:
routes/by domain,services/for shared logic,db.jsfor database - Frontend: HTML skeleton only, JS/CSS in separate files
- Every project gets
admin.html+routes/admin.jsfor config hot-reload
Project Type Selection
Determine project type, then read the corresponding reference:
| Type | Signals | Reference |
|---|---|---|
| H5 Game | Canvas, Phaser, Matter.js, game loop, sprites | references/game.md |
| Data Tool | Crawler, scraper, scheduler, data sync, analytics | references/tool.md |
| Content/Utility | Generator, library, publisher, file processing | references/tool.md |
| Dashboard/Monitor | Charts, real-time, alerts, metrics | references/tool.md |
| API Service | REST endpoints, middleware, microservice | references/tool.md |
| SDK/Library | Shared module, build step, multi-consumer | references/sdk.md |
Quick Start (All Types)
- Identify project type from table above
- Read the corresponding reference file
- Create directory structure per the reference
- Extract hardcoded values →
config.json - Split large files by function (each <400 lines)
- Add
routes/admin.js+admin.html - Frontend:
config.jsfetches/api/configat startup, code readsGAME_CONFIG.xxxorAPP_CONFIG.xxx - Test locally → backup → deploy
config.json Pattern (Universal)
// Server: load and serve config
const config = JSON.parse(fs.readFileSync('./config.json', 'utf8'));
app.get('/api/config', (req, res) => {
const safe = { ...config };
delete safe.admin; // strip secrets
res.json(safe);
});
// Admin: hot-reload
app.post('/admin/config', requireAdmin, (req, res) => {
fs.writeFileSync('./config.json.bak', fs.readFileSync('./config.json'));
fs.writeFileSync('./config.json', JSON.stringify(req.body, null, 2));
Object.assign(config, req.body);
res.json({ ok: true });
});
Admin Dashboard Pattern (Universal)
admin.html auto-generates form from config structure:
- Password login (
x-admin-passwordheader) - Visual config editor with save + hot-reload
- Stats overview (users/data/uptime)
- Config backup history + restore
Why This Matters
Large single files consume massive context tokens when AI reads them:
- 3000-line file → ~40K tokens per read (20% of 200K window)
- 200-line module → ~2.7K tokens per read (1.3% of window)
- Result: 10-15 productive rounds vs 3-5 before context compression
Version History
- e0220ca Current 2026-07-05 22:16
