Back to Details

create-core-knowledge

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill: generate-core-knowledge

Skill: generate-core-knowledge

<purpose> Instructs the agent to perform a deep recursive analysis of the current repository and populate a `COREKNOWLEDGE_FOLDER` with a canonical set of technical documents that any future agent or developer can rely on as the definitive source of truth for the project.
Unless the user specifies otherwise, 
COREKNOWLEDGE_FOLDER
= 
.agents/core-knowledge
(relative to the workspace root). </purpose>
<instructions>
<purpose> 指示Agent对当前仓库进行深度递归分析，并在`COREKNOWLEDGE_FOLDER`中生成一套标准化技术文档，供未来的Agent或开发者作为项目的权威参考依据。
除非用户另有指定，
COREKNOWLEDGE_FOLDER
= 
.agents/core-knowledge
（相对于工作区根目录）。 </purpose>
<instructions>

Phase 0 — Locate and Read Existing Knowledge

阶段0 — 定位并读取现有知识

  1. Resolve 
    COREKNOWLEDGE_FOLDER
    :
    • If the user explicitly named a folder, use that path.
    • Otherwise default to 
      .agents/core-knowledge
      at the workspace root.
  2. Check whether 
    COREKNOWLEDGE_FOLDER
    exists and list its contents.
    • If it contains any 
      .md
      , 
      .txt
      , or 
      .json
      files, read every one of them in full before doing anything else.
    • Treat their content as authoritative context that must be preserved and extended — never contradicted or silently discarded.
  3. If 
    COREKNOWLEDGE_FOLDER
    does not exist yet, create it.
  1. 解析
    COREKNOWLEDGE_FOLDER
    :
    • 如果用户明确指定了文件夹路径，则使用该路径。
    • 否则默认使用工作区根目录下的
      .agents/core-knowledge
      。
  2. 检查
    COREKNOWLEDGE_FOLDER
    是否存在并列出其内容。
    • 若文件夹中包含
      .md
      、
      .txt
      或
      .json
      文件，在执行其他操作前完整读取每一个文件。
    • 将这些文件的内容视为必须保留和扩展的权威上下文——绝不能与之矛盾或静默丢弃。
  3. 若
    COREKNOWLEDGE_FOLDER
    尚未存在，则创建该文件夹。

Phase 1 — Project Reconnaissance

阶段1 — 项目侦察

Perform a recursive scan of the repository. Collect enough evidence to answer each question below before writing a single document. Read files in parallel where possible.
对仓库进行递归扫描。在撰写任何文档之前，收集足够的信息以回答以下每个问题。尽可能并行读取文件。

1.1 Repository Layout

1.1 仓库布局

  • What is the top-level folder structure?
  • Is there a primary application subfolder (e.g. a framework project inside a monorepo)?
  • What framework / runtime is in use (Node, Python, Java, …)? Check 
    package.json
    , 
    pyproject.toml
    , 
    pom.xml
    , 
    go.mod
    , etc.
  • 顶层文件夹结构是什么？
  • 是否存在主应用子文件夹（例如单体仓库中的框架项目）？
  • 使用了什么框架/运行时（Node、Python、Java等）？检查
    package.json
    、
    pyproject.toml
    、
    pom.xml
    、
    go.mod
    等文件。

1.2 Source Code Structure

1.2 源代码结构

  • Map 
    src/
    (or equivalent) top-level folders: api modules, services, utilities, types, middleware, plugins.
  • Identify the entry point(s) of the application.
  • 绘制
    src/
    （或等效目录）的顶层文件夹映射：API模块、服务、工具、类型、中间件、插件。
  • 识别应用的入口点。

1.3 API / Endpoint Design

1.3 API / 端点设计

  • Enumerate all API modules or route files.
  • Identify any versioning strategy (URL prefix, header, file naming like 
    v2-*
    ).
  • Note any intentional exceptions to the versioning rule (e.g. legacy endpoints kept for migration reasons).
  • Document the folder/file naming convention for controllers, services, and routes.
  • 枚举所有API模块或路由文件。
  • 识别任何版本控制策略（URL前缀、请求头、类似
    v2-*
    的文件命名方式）。
  • 记录版本控制规则的任何有意例外情况（例如为迁移保留的旧端点）。
  • 记录控制器、服务和路由的文件夹/文件命名规范。

1.4 Integration / External Services Layer

1.4 集成 / 外部服务层

  • Find HTTP client code that calls third-party or internal APIs.
  • Document the data flow: external API response → mapper/transformer → typed internal model → controller response.
  • Identify authentication mechanisms (API keys, Basic Auth, OAuth, JWT, etc.).
  • 查找调用第三方或内部API的HTTP客户端代码。
  • 记录数据流：外部API响应 → 映射器/转换器 → 类型化内部模型 → 控制器响应。
  • 识别认证机制（API密钥、基础认证、OAuth、JWT等）。

1.5 Configuration & Feature Management

1.5 配置与功能管理

  • Read base config files and all environment-specific config overrides.
  • Find all environment variables (
    .env
    , 
    config/*.ts
    , 
    *.yml
    , 
    *.toml
    , …).
  • Identify boolean feature flags and what behaviour they gate.
  • Document how multi-tenant or multi-client config is split (if applicable).
  • 读取基础配置文件和所有环境特定的配置覆盖文件。
  • 查找所有环境变量（
    .env
    、
    config/*.ts
    、
    *.yml
    、
    *.toml
    等）。
  • 识别布尔型功能开关及其控制的行为。
  • 记录多租户或多客户端配置的拆分方式（如适用）。

1.6 Authentication & Authorization

1.6 认证与授权

  • Identify the auth strategy (JWT, session, API key, Cognito, Auth0, …).
  • Document how the identity is populated into request context and consumed downstream.
  • Note any role or policy-based access control patterns.
  • 识别认证策略（JWT、会话、API密钥、Cognito、Auth0等）。
  • 记录身份如何填充到请求上下文并在下游被使用。
  • 记录任何基于角色或策略的访问控制模式。

1.7 Database & Migrations

1.7 数据库与迁移

  • Identify the database driver and ORM/query-builder.
  • Locate migration files and document the migration strategy.
  • Document model/schema conventions.
  • 识别数据库驱动和ORM/查询构建器。
  • 定位迁移文件并记录迁移策略。
  • 记录模型/架构规范。

1.8 CI/CD Pipeline

1.8 CI/CD流水线

  • Read pipeline config files (
    .gitlab-ci.yml
    , 
    .github/workflows/*.yml
    , 
    Jenkinsfile
    , …).
  • Map stages, jobs, trigger conditions (branch, tag, manual), and deployment targets.
  • 读取流水线配置文件（
    .gitlab-ci.yml
    、
    .github/workflows/*.yml
    、
    Jenkinsfile
    等）。
  • 映射阶段、任务、触发条件（分支、标签、手动）和部署目标。

1.9 Cloud / Serverless Functions

1.9 云 / 无服务器函数

  • Check for serverless function folders (AWS Lambda, GCP Cloud Functions, Azure Functions, …).
  • For each function, identify: trigger type, purpose, runtime, and relationship to the main application.
  • 检查是否存在无服务器函数文件夹（AWS Lambda、GCP Cloud Functions、Azure Functions等）。
  • 针对每个函数，识别：触发器类型、用途、运行时以及与主应用的关系。

1.10 Tests

1.10 测试

  • Locate test folders and identify the testing framework.
  • Note the split between unit and integration tests if present.
  • 定位测试文件夹并识别测试框架。
  • 记录单元测试与集成测试的划分（如存在）。

Phase 2 — Document Generation

阶段2 — 文档生成

Create or update the following files inside 
COREKNOWLEDGE_FOLDER
. If a file already exists, extend or correct it — do not overwrite content that is still accurate.
在
COREKNOWLEDGE_FOLDER
内创建或更新以下文件。若文件已存在，仅扩展或修正内容——不得覆盖仍准确的内容。

architecture.md

architecture.md

Must include:
  • Directory map: An ASCII tree of the 
    src/
    folder (or equivalent) with one-line descriptions per node.
  • Data flow diagram: ASCII diagram showing how a request travels from client → auth/middleware → controller → external service client → mapper → response.
  • API versioning convention: Explain the URL and file-naming patterns. Explicitly call out any intentional exceptions (legacy endpoints, migration holdouts, etc.).
  • Authentication flow: How tokens/credentials are validated and how user identity is injected into request context.
  • Coding conventions checklist: Step-by-step rules for creating a new endpoint, including: folder structure, file naming, auth policy usage, input validation library, error response helpers, external call discipline, and type conventions.
  • Content-type / model conventions (if the framework has a CMS or ORM layer).
必须包含：
  • 目录映射：
    src/
    文件夹（或等效目录）的ASCII树状图，每个节点附带一行描述。
  • 数据流图：ASCII图展示请求从客户端 → 认证/中间件 → 控制器 → 外部服务客户端 → 映射器 → 响应的流转过程。
  • API版本控制规范：解释URL和文件命名模式。明确指出任何有意的例外情况（旧端点、迁移遗留项等）。
  • 认证流程：令牌/凭证如何验证，以及用户身份如何注入请求上下文。
  • 编码规范清单：创建新端点的分步规则，包括：文件夹结构、文件命名、认证策略使用、输入验证库、错误响应工具、外部调用规范和类型约定。
  • 内容类型 / 模型规范（若框架包含CMS或ORM层）。

business-idea.md

business-idea.md

Must include:
  • Product overview: What the system does and who uses it.
  • Client / tenant distinction: If multi-tenant, document each tenant's scope, commodity types, feature access, and any dedicated API modules.
  • Migration status: If an ongoing migration is in progress, document which tenants/features are ahead or behind and what gates the switch (feature flags, branches, etc.).
  • Key initiatives: Document any major in-progress feature initiatives (e.g. a billing project, a new data model, a "Huge-clients" performance initiative), their status, and how they affect code conventions.
  • CMS / editorial role: If the backend also manages editorial content, describe what content types drive frontend behaviour.
必须包含：
  • 产品概述：系统功能及用户群体。
  • 客户端 / 租户区分：若为多租户架构，记录每个租户的范围、商品类型、功能访问权限以及任何专用API模块。
  • 迁移状态：若正在进行迁移，记录哪些租户/功能已完成或滞后，以及切换的触发条件（功能开关、分支等）。
  • 关键举措：记录任何正在进行的重大功能开发计划（例如计费项目、新数据模型、“大客户”性能优化计划）、其状态以及对代码规范的影响。
  • CMS / 编辑角色：若后端同时管理编辑内容，描述哪些内容类型会驱动前端行为。

feature-flags.md

feature-flags.md

Must include:
  • A table or section for every environment variable and feature flag found, with: env var name, config key path, type, default value, what it gates, and which files reference it.
  • Separately document any runtime toggles (flags stored in a database or admin panel rather than env vars), including who can change them and the effect on behaviour.
必须包含：
  • 为每一个找到的环境变量和功能开关创建表格或章节，内容包括：环境变量名称、配置键路径、类型、默认值、控制的行为以及引用它的文件。
  • 单独记录任何运行时开关（存储在数据库或管理面板而非环境变量中的开关），包括可修改开关的人员以及对行为的影响。

deployment.md

deployment.md

Must include:
  • Infrastructure overview table: hosting platform, region, auth service, logging, storage, CDN, database.
  • Environment inventory: every named environment (dev, uat, staging, prod, etc.) with its URL, hosting resource name, and the tenant/client it serves.
  • Local development setup: prerequisites, commands to install, build, and start the server for each company/environment variant.
  • CI/CD pipeline walkthrough: stages, per-job trigger rules and approval requirements, artefact flow.
  • Deployment procedures per environment tier (automatic vs manual, branch/tag conventions).
  • Troubleshooting: document any known recurring deploy issues and their resolution steps.
  • Branching model: document the Git branching strategy and how it maps to environments.
必须包含：
  • 基础设施概览表：托管平台、区域、认证服务、日志、存储、CDN、数据库。
  • 环境清单：所有命名环境（dev、uat、staging、prod等）及其URL、托管资源名称和服务的租户/客户端。
  • 本地开发设置：前置条件、针对不同公司/环境变体的安装、构建和启动服务器的命令。
  • CI/CD流水线详解：阶段、每个任务的触发规则和审批要求、制品流转。
  • 各环境层级的部署流程（自动 vs 手动、分支/标签规范）。
  • 故障排查：记录任何已知的重复部署问题及其解决步骤。
  • 分支模型：记录Git分支策略及其与环境的映射关系。

<integration-name>.md
(one file per significant external integration, if present)

<integration-name>.md
（每个重要外部集成对应一个文件，若存在）

Examples: 
aws-lambdas.md
, 
stripe-integration.md
, 
salesforce-integration.md
Each integration file must include:
  • Inventory table: every function/endpoint with its trigger/event type, client/tenant scope, and environment scope.
  • Detailed logic description per item.
  • Client or tenant differences within the same integration.
  • SDK/runtime version history if multiple versions coexist.
  • Deployment/update procedure for that integration.
  • How the integration relates to backend request processing.
示例：
aws-lambdas.md
、
stripe-integration.md
、
salesforce-integration.md
每个集成文件必须包含：
  • 清单表格：每个函数/端点的触发器/事件类型、客户端/租户范围、环境范围。
  • 每个项的详细逻辑描述。
  • 同一集成内的客户端或租户差异。
  • 若存在多个版本共存，记录SDK/运行时版本历史。
  • 该集成的部署/更新流程。
  • 集成与后端请求处理的关系。

Phase 3 — Source-of-Truth Oath

阶段3 — 权威参考誓言

Append the following block verbatim at the top of 
architecture.md
(immediately after the H1 title):
> **Source-of-Truth oath**: Before generating any code, reference the files in this
> core-knowledge folder to ensure naming, file placement, and architectural patterns
> match the project's established standards — specifically respecting any
> versioning distinctions and client/tenant mapping logic documented here.
</instructions> <constraints> - Do NOT overwrite content in existing knowledge files that is still accurate. Extend or correct only. - Do NOT fabricate details that are not present in the codebase. If something is unclear, say so explicitly in the document. - Do NOT create additional markdown files outside `COREKNOWLEDGE_FOLDER` unless the user requests it. - Every document must be written for a future agent reader: be precise, use exact file paths, code identifiers, and command strings rather than vague prose. - If a section of a document is not applicable to this project (e.g. no serverless functions), omit that section rather than leaving a placeholder. </constraints>
<output_format> After all files are written, reply to the user with a brief confirmation listing:
  • Each file created or updated (as a workspace-relative link)
  • One sentence describing what was added or changed in each file </output_format>
将以下块内容逐字添加到
architecture.md
的顶部（紧跟H1标题之后）：
> **Source-of-Truth oath**: Before generating any code, reference the files in this
> core-knowledge folder to ensure naming, file placement, and architectural patterns
> match the project's established standards — specifically respecting any
> versioning distinctions and client/tenant mapping logic documented here.
</instructions> <constraints> - 不得覆盖现有知识文件中仍准确的内容，仅可扩展或修正错误内容。 - 不得编造代码库中不存在的细节。若有内容不明确，需在文档中明确说明。 - 除非用户要求，不得在`COREKNOWLEDGE_FOLDER`之外创建额外的Markdown文件。 - 所有文档必须面向未来的Agent读者撰写：内容需精准，使用确切的文件路径、代码标识符和命令字符串，而非模糊的描述。 - 若文档中的某一部分不适用于当前项目（例如无服务器函数），则省略该部分，而非保留占位符。 </constraints>
<output_format> 所有文件撰写完成后，向用户回复一份简要确认信息，列出：
  • 每个创建或更新的文件（以工作区相对链接形式）
  • 一句话描述每个文件新增或修改的内容 </output_format>