Back to Details

kf-setup-project

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Setup Project

项目设置

Create the smallest evidence-backed map that lets a fresh Codex session navigate, act, and validate safely.
创建最小化的、基于证据的指引地图，让全新的Codex会话能够安全地导航、执行操作并验证结果。

Workflow

工作流程

  1. Resolve the requested setup scope and repository root. Inspect existing guidance, core documentation, workspace configuration, and task commands before editing.
  2. Identify only the boundaries, canonical destinations, commands, and constraints that materially change future decisions. Never invent commands or layouts.
  3. Separate weak observations from established conventions supported by repeated code, accepted decisions, or explicit maintainer direction. Treat a current status section or one implementation as an example rather than a mandate.
  4. Put each fact at its narrowest durable owner: root guidance for shared routing and constraints, nested guidance for subtree differences, documentation for substantial knowledge, and skills for reusable procedures.
  5. Create or complete guidance with short, purpose-labelled links instead of reproducing the linked content.
  6. Validate inheritance, links, and commands from the scopes where agents will use them, then review the diff for speculation and unnecessary always-loaded text.
  1. 明确请求的设置范围和仓库根目录。在编辑前，检查现有指南、核心文档、工作区配置和任务命令。
  2. 仅识别那些会对未来决策产生实质性影响的边界、标准目标路径、命令和约束条件。切勿凭空创造命令或布局。
  3. 将薄弱观察结果与经重复代码、已接受决策或明确维护者指示支持的既定惯例区分开来。将当前状态部分或单一实现视为示例而非强制要求。
  4. 将每个事实放置在其最窄的持久归属位置：根指南用于共享路由和约束，嵌套指南用于子树差异，文档用于大量知识，技能用于可复用流程。
  5. 创建或补全指南时，使用简短的、带有用途标签的链接，而非复制链接内容。
  6. 从Agent将使用这些内容的范围验证继承关系、链接和命令，然后检查差异内容是否存在推测和不必要的预加载文本。

Root retention test

根目录留存测试

Before adding an instruction to the root 
AGENTS.md
, require all of the following:
  • it changes agent behavior or a recurring technical decision;
  • it applies across most unrelated work in the repository;
  • the root is its narrowest correct scope; and
  • linking to an existing canonical source would not be sufficient.
Being accurate, useful somewhere, or repository-wide in subject matter is not enough. A root guide is a routing layer and shared guardrail, not an onboarding summary, project inventory, architecture digest, product specification, or status report.
Root guidance may identify workspace mechanics, common command entry points, shared protected boundaries, generated guidance or skill metadata, and when to read canonical documents. Keep explanations, schemas, inventories, accepted decision detail, temporary implementation status, and examples in their owning documents or narrower guidance.
在向根目录
AGENTS.md
添加指令前，需满足以下所有条件：
  • 它会改变Agent行为或重复出现的技术决策；
  • 它适用于仓库中大多数不相关的工作场景；
  • 根目录是其最恰当的最小范围；
  • 链接到现有标准来源不足以满足需求。
仅准确、在某些场景有用或主题覆盖整个仓库是不够的。根指南是一个路由层和共享防护栏，而非入门摘要、项目清单、架构摘要、产品规格或状态报告。
根指南可包含工作区机制、常见命令入口点、共享保护边界、生成的指南或技能元数据，以及何时阅读标准文档的说明。将解释、架构图、清单、已接受决策细节、临时实现状态和示例放在其归属的文档或更窄范围的指南中。

Monorepos

单体仓库（Monorepos）

  • Default to the current directory or user-named subtree. Setup at the workspace root updates shared root guidance only unless the user requests broader setup.
  • Use workspace configuration and actual project boundaries as evidence; do not infer a monorepo or member layout from folder names alone.
  • Do not summarize every member in root guidance. Identify how members and their nearest guidance are discovered, then place member commands, architecture, conventions, and examples with that member.
  • Add a nested 
    AGENTS.md
    only when a subtree has material differences. Make it additive and do not copy inherited root rules.
  • Compare ancestor and nested guidance semantically. When a more specific nested rule covers a concern that matters only there, omit the generic root version.
  • A nested guide may retain member commands, security invariants, generated-file rules, naming boundaries, and canonical patterns that repeatedly guide work in that subtree. Put explanations and broad architecture descriptions in member documentation.
  • Record cross-member coordination only when it changes how work must be performed; put substantial explanation in canonical documentation.
  • 默认使用当前目录或用户指定的子树。在工作区根目录进行设置时，仅更新共享根指南，除非用户要求更广泛的设置。
  • 以工作区配置和实际项目边界为依据；切勿仅根据文件夹名称推断单体仓库或成员布局。
  • 不要在根指南中总结每个成员。说明如何发现成员及其最近的指南，然后将成员命令、架构、惯例和示例与该成员放在一起。
  • 仅当子树存在实质性差异时，才添加嵌套的
    AGENTS.md
    。使其仅包含增量内容，不要复制继承的根目录规则。
  • 从语义上比较祖先和嵌套指南。当更具体的嵌套规则仅适用于该子树的特定问题时，省略通用的根目录版本。
  • 嵌套指南可保留成员命令、安全不变量、生成文件规则、命名边界以及在该子树中反复指导工作的标准模式。将解释和广泛的架构描述放在成员文档中。
  • 仅当跨成员协作会改变工作执行方式时，才记录相关内容；将详细解释放在标准文档中。

Sparse repositories

稀疏仓库

When evidence is insufficient, create only lightweight routing: known purpose, existing instructions, established documentation destination, and installed local skill location when relevant. Do not invent architecture, commands, conventions, examples, source trees, dependencies, or empty documentation. Recommend revisiting setup after representative implementation exists.
当证据不足时，仅创建轻量级路由：已知用途、现有指令、既定文档目标位置，以及相关的本地已安装技能位置。切勿凭空创造架构、命令、惯例、示例、源码树、依赖项或空文档。建议在有代表性的实现完成后重新审视设置。

Editing constraints

编辑约束

  • Preserve intentional existing content and make targeted changes; use 
    kf-maintain-guidance
    when established guidance needs cleanup or relocation.
  • Prefer concise positive directions and canonical links. Add prohibitions only for a concrete recurring risk and name the safe alternative or exception.
  • Describe an established implementation as the preferred current pattern, not as an exhaustive ban on alternative designs. Make a design absolute only when explicit maintainer intent or a concrete safety or compatibility boundary requires it.
  • Trace workspace commands through root scripts, task runners, and member scripts. State the verified invocation location separately from task ownership; a root proxy does not make a task root-owned, and a member-owned task may still have a root command.
  • Omit temporary statements about missing infrastructure, tests, or features. When the absence changes current work, express the durable action or authorization boundary instead of recording "not implemented yet" status.
  • Do not create one nested file per member, a standard document set, or a new layout merely for uniformity.
  • Do not modify user-level Codex configuration or global skills.
Success means a fresh session can find the right scope, evidence, commands, and validation without loading details unrelated to its task.
  • 保留现有有意设计的内容，进行针对性修改；当已确立的指南需要清理或迁移时，使用
    kf-maintain-guidance
    。
  • 优先使用简洁的正向指示和标准链接。仅针对具体的重复风险添加禁止性规定，并说明安全替代方案或例外情况。
  • 将已确立的实现描述为当前首选模式，而非对替代设计的全面禁止。仅当明确的维护者意图或具体的安全/兼容性边界要求时，才将设计定为绝对规则。
  • 追踪工作区命令通过根脚本、任务运行器和成员脚本的执行路径。分别说明已验证的调用位置和任务归属；根代理并不意味着任务归根目录所有，归成员所有的任务仍可能有根目录命令。
  • 省略关于缺失基础设施、测试或功能的临时声明。当缺失情况会影响当前工作时，表达持久的操作或授权边界，而非记录“尚未实现”的状态。
  • 不要仅为了统一性而给每个成员创建一个嵌套文件、一套标准文档集或新布局。
  • 不要修改用户级别的Codex配置或全局技能。
成功的标准是：全新会话无需加载与其任务无关的细节，即可找到正确的范围、证据、命令和验证方式。