← ClaudeAtlas

entry-card-craftlisted

把 Agent 入口文档(AGENTS.md 及同类)写成仓库的「简历」——结构与排版:以人为本的判决标准(好看、易看、愿意看)、简历与 README 的分工(注入/取用+三测试)、把故事讲清楚(不砍因果)、把文档排成 A4 看一遍再做终审。当「卡片读起来累、不好看、排版乱、简历和 README 怎么分工���想看看排出来什么样、给新项目写入口卡」时使用。关键词:仓库简历, 可读性, 排版, 实排页面, 打印 PDF, 页面终审, 末页合并, README 分工, AGENTS.md。
ranjiushu/repo-resume · ★ 1 · Code & Development · score 62
Install: claude install-skill ranjiushu/repo-resume
# 简历式优化:把入口文档写成仓库的「简历」 入口文档是仓库的「简历」(工作区同理):写给陌生人看,Agent 通常是它的第一读者。目标是简洁、美观、优雅——几分钟看明白这是哪儿、有什么规矩、细节去哪儿找。本成员管的是**判断与审美**:什么叫好、怎么分工、怎么排版、终审怎么过。体积、阈值、下沉动作归 entry-doc-governance;文风归 entry-deai-style;三条边界与分工秩序在聚合层 §〇。这套判据的理据收在 references/philosophy.md,按需加载;本文只留判据与动作。 第一原则:入口文档不是知识库,它是简历,也是人与 Agent 共用的上下文入口——而 Agent 的默认上下文是稀缺资源。 ## 〇、判准的立足点:以人为本 入口文档没有客观最优解,与其争论「多大最合适」,不如取一个能复核的标准:好看、易看、愿意看(读得下去、不被形式劝退,不是要写得动人)。人读得进去,才愿意改、愿意用、愿意把判断放进来,所以体积阈值只管有没有失控,判决权在人的阅读体验。默认读者是不熟悉这个项目的人,不是作者本人。完整论证与核心假设见 references/philosophy.md。 操作上三条。体积判据用 token(机器能强制的只有体积代理,归 entry-doc-governance),但终审要看**实排的页面**,像读者那样通读一遍,不只看一个数字。排版是可用的杠杆:真表格、留白、标题层级、长短句都为「愿意看」服务,值得为它们花掉一些页数。**打印可用而不跑页面,终审不算完成;打印不可用时,交付须显式标注「未经页面终审」。** 「简历」这个比方可以直接判决一段话的去留:读者是陌生人;放「从哪来、现在怎样」,不放生平流水账;不能撒谎,不该过期。它只借结构不借说服——不必打动谁,服务的是人际协同:让人知道从哪儿开始对话、该问什么。调性是交接说明,不是宣传文案,也不是流水账。 ### 与 README 的分工 简历管「简」与「历」:一眼看懂这是哪儿、要守什么,加上来历与现状。README 讲项目本身:在干什么、要去哪、影响上手的技术细节;它是项目自己的声音,换个负责人换调性,不必求统一。 判据不在内容类别,在**代价结构与触发时机**:入口文档被注入,每次开工都占一份上下文,只放「不知道就会做错」和「马上要用的入口」;README 被取用,代价只在被读时发生,放想了解才需要的东西。 三个测试判一条内容该放哪。**注射测试**——每次会话都必须读到吗?是,进简历。**违反测试**——不知道就会做错吗?会,简历里至少留一句加指针,细则仍可放 README。**删除测试**——删了会立刻坏吗?会坏,进简历。推论:同一事实只写一处,一处写、一处指;简历过期直接导致错误动作,README 过期只是误解,所以简历宁短勿滥,README 宁可写全。 ## 一、把故事讲清楚 长度不是目标函数,把故事讲清楚才是。第一次翻开它的 Agent 要能说出三件事:这是什么地方、为什么有这些规矩、细节去哪找——这三件事本身就是内容,不可指针化。一张每行都写着「→ 见某文件」的卡什么也没讲,读者得先跳出去才知道为什么要跳。页数陡增是信号,页数变小不是成绩;为保住因果与最短路径而多占的页面,是正当开销。 ## 二、人类刻度与打印层(页面终审) 人感觉不到 token 与字节,感觉到的是页面。打印层(scripts/print-entry-doc.sh)把入口文档真排成 A4 PDF 并报页数;实排含短行与行尾留白,与