docs: strengthen knowledge base indexes

docs/references/README.md

@@ -1,25 +1,34 @@
-# 🧭 基础指南
+# 参考资料
 
-> Vibe Coding 的核心理念、原则与方法论
+> `references/` 存放工程实践、技术栈、模板、清单、质量门禁和可复用经验。
 
-## 📖 核心方法论
+## 目录定位
 
-### 拼好码（胶水编程的超集）
-- [拼好码](../concepts/拼好码.md) - 复用成熟能力，用胶水代码连接、编排、适配业务流程
-- [语言层要素](../concepts/语言层要素.md) - 看懂 100% 代码的 8 个层级
+本目录不是入门教程，也不是研究笔记；它负责把已经相对稳定的工程经验整理成可执行、可检查、可复用的参考资料。
 
-### 理论基础
-- [递归自优化系统](../concepts/递归自优化系统.md) - 元方法论
-- [编程之道](../philosophy/编程之道.md) - 编程哲学
+| 文件 | 用途 |
+|:---|:---|
+| [工程实践](工程实践.md) | 项目架构、代码组织、开发经验、底层程序逻辑、AI 编程质量门禁与常见坑的统一入口 |
+| [技术栈](技术栈.md) | 软件系统常见技术栈、选型维度、组合案例与初学者学习路径 |
+| [AGENTS](AGENTS.md) | 本目录 Agent 操作规则 |
 
-### 软件工程基础
-- [问题求解](../concepts/问题求解.md) - 目标、现状、差距、标准与反馈迭代的底层能力
-- [系统构建方法](../concepts/系统构建方法.md) - 自顶向下、自底向上与分而治之的组合使用
-- [开发范式演进](../concepts/开发范式演进.md) - 从面向过程到云原生的工程组织方式演进
+## 相关核心概念
 
-### 工程实践
-- [工程实践](工程实践.md) - 项目架构、代码组织、开发经验、底层程序逻辑、AI 编程质量门禁与常见坑的统一入口
-- [技术栈](技术栈.md) - 软件系统常见技术栈、选型维度、组合案例与初学者学习路径
+- [拼好码](../concepts/拼好码.md) - 复用成熟能力，用胶水代码连接、编排、适配业务流程。
+- [问题求解](../concepts/问题求解.md) - 目标、现状、差距、标准与反馈迭代的底层能力。
+- [系统构建方法](../concepts/系统构建方法.md) - 自顶向下、自底向上与分而治之的组合使用。
+- [开发范式演进](../concepts/开发范式演进.md) - 从面向过程到云原生的工程组织方式演进。
+- [语言层要素](../concepts/语言层要素.md) - 看懂代码所需的语言层要素。
 
-## 🔗 相关资源
-- [入门指南](../getting-started/) - 从零开始
+## 相关哲学模型
+
+- [思维模型](../philosophy/思维模型.md) - 第一性原理、奥卡姆剃刀、多阶思维、状态空间等可复用认知工具。
+- [组合描述模型](../philosophy/组合描述模型.md) - 对象、状态、快照、序列、过程、变换、同一/差异与关系。
+- [编程之道](../philosophy/编程之道.md) - 编程哲学与工程判断。
+- [递归自优化系统](../concepts/递归自优化系统.md) - 元方法论与自优化生成系统模型。
+
+## 维护规则
+
+- 检查清单、模板、质量门禁和经验类内容优先收敛到 [工程实践](工程实践.md)。
+- 技术选型、技术栈组合和学习路径优先收敛到 [技术栈](技术栈.md)。
+- 新技术、工具趋势、优秀 repo 解析先放入 [research](../research/README.md)，稳定后再迁入本目录。

docs/references/工程实践.md

@@ -2,6 +2,22 @@
 
 > 本文档合并原 `项目架构模板.md`、`代码组织.md`、`开发经验.md`、`底层程序逻辑设计与工程优化项.md` 与 `AI编程质量门禁与常见坑.md`，作为项目架构、代码组织、开发经验、底层程序逻辑、AI 编程质量门禁与常见坑的统一入口。
 
+## 核心摘要
+
+工程实践的核心目标是把“AI 可能写对”变成“系统必须可验证”：任务开始前写清目标、边界和验收标准；实现过程中用拼好码优先复用成熟方案；交付前用测试、CI、脚本、类型、schema、检查清单和代码审查形成硬门禁。
+
+本文件适合作为开发者和 Agent 的工程约束手册：遇到架构设计、代码组织、质量门禁、常见坑、环境问题、Git 操作和项目维护时，优先在这里查规则和检查项。
+
+## 顶部导航
+
+| 主题 | 用途 |
+|:---|:---|
+| [项目架构模板](#1-项目架构模板) | 判断目录、模块、边界和职责是否清楚 |
+| [代码组织](#2-代码组织) | 检查命名、分层、依赖、状态和可维护性 |
+| [开发经验](#3-开发经验) | 沉淀任务推进、协作、复盘和交付经验 |
+| [AI 编程质量门禁与常见坑](#4-ai-编程质量门禁与常见坑) | 把验收标准转成测试、CI、脚本、类型、schema 或清单 |
+| [底层程序逻辑设计与工程优化项](#5-底层程序逻辑设计与工程优化项) | 用运行、并发、数据、性能和可观测模型约束实现 |
+
 ## 使用方式
 
 - 新项目从「项目架构模板」开始，先确定目录、边界、门禁和检查清单。

docs/references/技术栈.md

@@ -1,6 +1,30 @@
-# 技术栈
-
-# 一、什么是技术栈
+# 技术栈
+
+> 本文件是技术栈参考入口，帮助读者理解软件系统通常由哪些技术层组成、不同场景如何组合技术栈、初学者应该如何选择学习路径。
+
+## 核心摘要
+
+技术栈不是单个框架或语言，而是一组完成系统交付所需的技术组合，包括前端、后端、数据库、缓存、部署、监控、测试、AI、数据工程、安全和运维工具。选择技术栈时，不只看技术是否流行，还要看项目目标、团队能力、维护成本、生态成熟度、部署环境、合规要求和替换路径。
+
+本文件适合三类场景：新手建立技术全景，开发者为项目选型，Agent 在生成方案前理解“应该优先复用哪些成熟技术组合”。
+
+## 顶部导航
+
+| 主题 | 用途 |
+|:---|:---|
+| [什么是技术栈](#一什么是技术栈) | 建立基本概念，理解技术组合而非单点技术 |
+| [技术栈通常包含哪些部分](#二技术栈通常包含哪些部分) | 前端、后端、数据库、部署、AI、数据、安全等层级 |
+| [常见项目对应技术栈](#十三常见项目对应技术栈) | Web、移动端、桌面端、全栈、游戏、数据工程等组合案例 |
+| [如何选择技术栈](#十四如何选择技术栈) | 从目标、约束、团队能力、生态成熟度和长期维护评估方案 |
+| [初学者应该学什么技术栈](#十五初学者应该学什么技术栈) | 从可交付项目出发，选择最小必要技术路线 |
+
+## 使用方式
+
+- 做新项目选型时，先按项目类型定位候选技术栈，再用维护成本和成熟度筛选。
+- 给 AI 提需求时，把目标平台、团队能力、部署环境、数据规模和必须规避的技术写清楚。
+- 当成熟技术栈能满足需求时，遵循拼好码原则，优先复用成熟方案，不默认自研底层能力。
+
+# 一、什么是技术栈
 
 **技术栈**，英文叫 **Technology Stack**，指开发一个软件系统时使用的一整套技术、框架、语言、工具和平台。
 
@@ -1528,4 +1552,4 @@ AI 路线：
 
 > Python + PyTorch + FastAPI + 大模型 API
 
-真正重要的不是“知道很多技术名词”，而是能用合适的技术栈，把一个项目稳定、清晰、可维护地做出来。
+真正重要的不是“知道很多技术名词”，而是能用合适的技术栈，把一个项目稳定、清晰、可维护地做出来。