entry-card-craftlisted
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 并报页数;实排含短行与行尾留白,与