Back to Details

adr-discover

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill: Descubrir ADRs en un proyecto existente

Skill：在现有项目中发现ADR

Analiza la estructura y el código de un repositorio para identificar decisiones arquitectónicas implícitas — elecciones de tecnología, patrones, convenciones o compromisos que están vivos en el código pero nunca se documentaron formalmente.
El output es una lista priorizada de ADRs candidatos. El usuario decide cuáles crear; el skill luego invoca 
adr-manage
para cada uno aprobado.
分析仓库的结构和代码，识别隐含的架构决策——即存在于代码中但从未正式记录的技术选择、模式、约定或取舍。
输出是优先级排序的候选ADR列表。由用户决定创建哪些；之后该Skill会为每个获批的候选ADR调用
adr-manage
。

Fase 1 — Orientación inicial

阶段1 — 初始定位

Antes de inspeccionar, determinar el alcance:
  1. Leer 
    .agents/MEMORY.md
     (si existe) para entender el stack y contexto ya conocido.
  2. Leer 
    docs/adr/
     para listar los ADRs ya existentes — nunca proponer un candidato que duplique uno existente (
    Accepted
    , 
    Proposed
    o 
    Draft
    ).
  3. Si el usuario no indicó ruta, asumir raíz del repositorio actual.
在检查之前，确定范围：
  1. 读取
    .agents/MEMORY.md
    （如果存在），以了解已知的技术栈和上下文。
  2. 读取
    docs/adr/
    ，列出已有的ADR——绝不提出与现有ADR（
    Accepted
    、
    Proposed
    或
    Draft
    状态）重复的候选。
  3. 如果用户未指定路径，默认当前仓库的根目录。

Fase 2 — Inspección del proyecto

阶段2 — 项目检查

Explorar en este orden, acumulando señales:
按以下顺序探索，收集线索：

2a. Estructura de carpetas

2a. 文件夹结构

bash
find . -maxdepth 3 -type d | grep -v node_modules | grep -v .git | grep -v __pycache__
Inferir: monorepo vs monolito, separación por capas/dominios, presencia de módulos, microservicios, etc.
bash
find . -maxdepth 3 -type d | grep -v node_modules | grep -v .git | grep -v __pycache__
推断：单体仓库还是单体应用、按层/领域划分、是否存在模块、微服务等。

2b. Manifiestos de dependencias

2b. 依赖清单

Leer todos los que apliquen según el stack detectado:
EcosistemaArchivos a leer
Node / JS / TS
package.json
, 
package-lock.json
, 
tsconfig.json
Python
pyproject.toml
, 
requirements.txt
, 
setup.cfg
, 
Pipfile
JVM
pom.xml
, 
build.gradle
, 
build.gradle.kts
.NET
*.csproj
, 
*.sln
Rust
Cargo.toml
Go
go.mod
Señales clave a extraer:
  • Framework web principal (Express, FastAPI, Spring, etc.)
  • ORM / cliente de base de datos
  • Bus de mensajes / queue
  • Herramientas de test
  • Bundler / transpilador
  • Librerías de autenticación / autorización
  • Clientes de servicios cloud
根据检测到的技术栈，读取所有适用的文件：
生态系统需读取的文件
Node / JS / TS
package.json
, 
package-lock.json
, 
tsconfig.json
Python
pyproject.toml
, 
requirements.txt
, 
setup.cfg
, 
Pipfile
JVM
pom.xml
, 
build.gradle
, 
build.gradle.kts
.NET
*.csproj
, 
*.sln
Rust
Cargo.toml
Go
go.mod
需提取的关键线索：
  • 主要Web框架（Express、FastAPI、Spring等）
  • ORM / 数据库客户端
  • 消息总线 / 队列
  • 测试工具
  • 打包工具 / 转译器
  • 认证 / 授权库
  • 云服务客户端

2c. Código fuente — patrones arquitectónicos

2c. 源代码 — 架构模式

Buscar evidencia de patrones en el código:
bash
undefined
在代码中寻找模式的证据：
bash
undefined

Detectar estructura de capas

检测分层结构

find src -type d | head -30
find src -type d | head -30

Buscar patrones de diseño comunes

查找常见设计模式

grep -r "Repository|Service|Controller|Handler|UseCase|Interactor" src --include=".ts" --include=".py" --include="*.java" -l 2>/dev/null | head -20
grep -r "Repository|Service|Controller|Handler|UseCase|Interactor" src --include=".ts" --include=".py" --include="*.java" -l 2>/dev/null | head -20

Detectar uso de inyección de dependencias

检测依赖注入的使用

grep -r "inject|Injectable|@Autowired|provide|container" src -l 2>/dev/null | head -10
undefined
grep -r "inject|Injectable|@Autowired|provide|container" src -l 2>/dev/null | head -10
undefined

2d. ADRs existentes

2d. 现有ADR

bash
ls docs/adr/*.md 2>/dev/null || echo "No hay ADRs"
Para cada ADR existente, leer solo el título y la sección 
## Decisión
(no cargar el documento completo si hay muchos).
bash
ls docs/adr/*.md 2>/dev/null || echo "No hay ADRs"
对于每个现有ADR，仅读取标题和
## Decisión
部分（如果数量较多，无需加载完整文档）。

Fase 3 — Identificación de candidatos

阶段3 — 候选识别

Para cada señal encontrada, evaluar si amerita un ADR usando estos criterios:
Incluir como candidato si:
  • Es una elección no obvia entre varias alternativas reales (ej: Redux vs Zustand, REST vs GraphQL)
  • Tiene consecuencias que afectan a múltiples partes del sistema
  • Sería costoso revertir sin una razón documentada
  • Un desarrollador nuevo podría cuestionarla razonablemente
Excluir si:
  • Ya está cubierta por un ADR existente
  • Es la opción por defecto obvia del stack (ej: usar Jest en un proyecto CRA)
  • Es una decisión de implementación, no arquitectónica
对于每个发现的线索，使用以下标准评估是否值得生成ADR：
列为候选的情况：
  • 是在多个实际备选方案中做出的非显而易见选择（例如：Redux vs Zustand，REST vs GraphQL）
  • 具有影响系统多个部分的后果
  • 若无记录的理由，撤销成本很高
  • 新开发人员可能会合理地质疑该决策
排除的情况：
  • 已被现有ADR覆盖
  • 是技术栈中显而易见的默认选项（例如：在CRA项目中使用Jest）
  • 是实现决策，而非架构决策

Categorías típicas a buscar

需查找的典型类别

CategoríaEjemplos de señales
Lenguaje / runtimeTypeScript strict, versión de Node/Python, uso de Deno/Bun
Arquitectura generalCapas (controller/service/repo), DDD, hexagonal, CQRS
PersistenciaElección de BD, ORM vs query builder, estrategia de migraciones
API / protocoloREST vs GraphQL vs tRPC, versioning de API
AutenticaciónJWT vs sesiones, proveedor OAuth, manejo de refresh tokens
Estado / UIGestión de estado global, SSR vs CSR, design system
TestingEstrategia de tests (unit/integration/e2e), mocking approach
ObservabilidadLogger elegido, estrategia de errores, tracing
ModularidadMonorepo strategy, barrel exports, límites de módulo
CI/CDPipeline elegido, estrategia de deploy, feature flags
类别线索示例
语言 / 运行时TypeScript严格模式、Node/Python版本、使用Deno/Bun
整体架构分层（Controller → Service → Repository）、DDD、六边形架构、CQRS
持久化数据库选择、ORM vs 查询构建器、迁移策略
API / 协议REST vs GraphQL vs tRPC、API版本控制
认证JWT vs 会话、OAuth提供商、刷新令牌管理
状态 / UI全局状态管理、SSR vs CSR、设计系统
测试测试策略（单元/集成/e2e）、Mock方法
可观测性所选日志工具、错误策略、链路追踪
模块化单体仓库策略、桶导出、模块边界
CI/CD所选流水线、部署策略、功能开关

Fase 4 — Presentación de candidatos

阶段4 — 候选展示

Mostrar la lista al usuario en este formato:
undefined
按以下格式向用户展示列表：
undefined

ADRs Candidatos Descubiertos

发现的候选ADR

🟢 Alta prioridad (decisiones con amplio impacto)

🟢 高优先级（影响范围广的决策）

[C-01] Uso de TypeScript en modo strict
  • Evidencia: 
    tsconfig.json
    con 
    "strict": true
  • Por qué es una decisión: afecta toda la experiencia de desarrollo y la curva de onboarding
  • ADR existente: ninguno
[C-02] Arquitectura en capas (Controller → Service → Repository)
  • Evidencia: estructura de carpetas 
    src/controllers/
    , 
    src/services/
    , 
    src/repositories/
  • Por qué es una decisión: define los límites de responsabilidad en todo el sistema
  • ADR existente: ninguno
[C-01] 使用TypeScript严格模式
  • 证据：
    tsconfig.json
    中包含
    "strict": true
  • 为何是决策：影响整个开发体验和入门学习曲线
  • 现有ADR：无
[C-02] 分层架构（Controller → Service → Repository）
  • 证据：文件夹结构
    src/controllers/
    、
    src/services/
    、
    src/repositories/
  • 为何是决策：定义了整个系统的职责边界
  • 现有ADR：无

🟡 Media prioridad (decisiones relevantes, alcance acotado)

🟡 中优先级（相关决策，范围有限）

[C-03] Uso de Prisma como ORM
  • Evidencia: 
    @prisma/client
    en 
    package.json
    , carpeta 
    prisma/
  • Por qué es una decisión: alternativa a TypeORM, Drizzle, Sequelize — no es la única opción
  • ADR existente: ninguno
[C-03] 使用Prisma作为ORM
  • 证据：
    package.json
    中的
    @prisma/client
    、
    prisma/
    文件夹
  • 为何是决策：有TypeORM、Drizzle、Sequelize等备选方案——并非唯一选择
  • 现有ADR：无

⚪ Baja prioridad (convenciones, menor impacto)

⚪ 低优先级（约定，影响较小）

[C-04] ESLint + Prettier para linting y formato
  • Evidencia: 
    .eslintrc.js
    , 
    .prettierrc
  • Por qué es una decisión: establece el estándar de calidad de código del equipo
  • ADR existente: ninguno
Total: X candidatos encontrados. ¿Cuáles quieres documentar como ADR?

Tras mostrar la lista, preguntar:

> "¿Cuáles candidatos quieres crear como ADR? Puedes indicarlos por código (C-01, C-03…), por rango (C-01 a C-04), o decir 'todos los de alta prioridad'."

---
[C-04] 使用ESLint + Prettier进行代码检查和格式化
  • 证据：
    .eslintrc.js
    、
    .prettierrc
  • 为何是决策：确立了团队的代码质量标准
  • 现有ADR：无
总计：发现X个候选ADR。你想要将哪些记录为ADR？

展示列表后，询问：

> "你想要将哪些候选创建为ADR？可以通过编号（C-01、C-03…）、范围（C-01至C-04），或说明‘所有高优先级’来指定。"

---

Fase 5 — Creación de ADRs aprobados

阶段5 — 创建获批的ADR

Por cada candidato aprobado por el usuario:
  1. Invocar el skill 
    adr-manage
    pasando como contexto:
    • El título sugerido
    • La evidencia encontrada (como contexto para la sección 
      ## Contexto
      )
    • La decisión inferida
    • Las alternativas implícitas detectadas (si las hay)
  2. Dejar que 
    adr-manage
    ejecute su flujo completo (incluyendo preguntar decisores, estado, etc.).
  3. Una vez creado cada ADR, continuar con el siguiente candidato aprobado.
对于每个用户获批的候选：
  1. 调用
    adr-manage
    Skill，并传入以下上下文：
    • 建议的标题
    • 发现的证据（作为
      ## Contexto
      部分的上下文）
    • 推断出的决策
    • 检测到的隐含备选方案（如果有）
  2. 让
    adr-manage
    执行完整流程（包括询问决策者、状态等）。
  3. 每个ADR创建完成后，继续处理下一个获批的候选。

Notas de comportamiento

行为说明

  • No inventar decisiones. Si la evidencia es ambigua, mencionar la incertidumbre en la columna "Evidencia" y marcarlo como baja prioridad.
  • No proponer ADRs triviales. "Usamos Git" no es un ADR.
  • No repetir trabajo. Si ya existe un ADR que cubre la decisión, omitir el candidato y mencionarlo en un pie de página: "X decisiones omitidas por estar ya documentadas."
  • Priorizar calidad sobre cantidad. Mejor 4 candidatos sólidos que 12 rellenos.
  • Idioma: seguir la convención de 
    .agents/MEMORY.md
    ; si no existe, usar el idioma del mensaje del usuario.
  • 不得编造决策。如果证据不明确，在“证据”栏中提及不确定性，并标记为低优先级。
  • 不得提出无关紧要的ADR。“我们使用Git”不属于ADR范畴。
  • 不得重复工作。如果已有ADR涵盖该决策，忽略候选并在页脚提及：“因已记录而忽略X项决策。”
  • 优先质量而非数量。4个可靠的候选优于12个凑数的候选。
  • 语言：遵循
    .agents/MEMORY.md
    中的约定；如果不存在，使用用户消息的语言。