Back to Details

papyrus-maximus

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

papyrus-maximus

papyrus-maximus

Project documentation that stays useful. For humans and agents.
始终实用的项目文档，面向人类和Agent使用。

Structure

结构

project/
  README.md          ← humans: what is this, how to run it
  AGENTS.md          ← agents: project rules, stack, commands
  CLAUDE.md          ← symlink → AGENTS.md
  docs/
    ARCHITECTURE.md  ← how the system works (diagrams > text)
    *.md             ← guides, references, anything useful
    plans/           ← specs, execution plans, living docs
That's it. No nested agent zones. No session notes folder.
project/
  README.md          ← 面向人类：项目介绍、运行方法
  AGENTS.md          ← 面向Agent：项目规则、技术栈、命令
  CLAUDE.md          ← 符号链接 → AGENTS.md
  docs/
    ARCHITECTURE.md  ← 系统工作原理（图 > 文字）
    *.md             ← 指南、参考文档、所有有用内容
    plans/           ← 规范、执行计划、活性文档
就这么多，没有嵌套的Agent专属区域，没有会话笔记文件夹。

File Roles

文件角色

README.md

README.md

For humans. High-level only.
SectionContent
WhatOne paragraph — what does this do?
Getting StartedClone, install, run. Copy-pasteable.
UsageKey commands / API surface
ContributingHow to dev, test, deploy
No architecture. No internal module descriptions. No detailed folder trees.
面向人类，仅包含高层级信息。
板块内容
项目介绍一段话讲清楚项目用途
快速开始克隆、安装、运行步骤，可直接复制执行
使用说明核心命令/API 对外暴露能力
贡献指南开发、测试、部署的方法
不要放架构内容、内部模块说明、详细的文件夹树。

AGENTS.md

AGENTS.md

For coding agents. Under 150 lines.
SectionContent
StackLanguages, frameworks, key deps
CommandsBuild, test, lint, deploy — exact commands
ConventionsNaming, patterns, gotchas
ArchitectureOne sentence + "see docs/ARCHITECTURE.md"
If it's growing past 150 lines, move content to 
docs/
.
面向编码Agent，内容控制在150行以内。
板块内容
技术栈编程语言、框架、核心依赖
命令构建、测试、lint、部署的精确命令
约定命名、设计模式、注意事项
架构一句话说明 + "详见 docs/ARCHITECTURE.md"
如果内容超过150行，把额外内容移到
docs/
目录下。

docs/ARCHITECTURE.md

docs/ARCHITECTURE.md

How the system is built. Diagram-first, text-second.
Use mermaid diagrams liberally:
  • System context → who talks to what (C4 level 1)
  • Component diagram → major modules and boundaries (C4 level 2)
  • Sequence diagrams → key flows
  • State diagrams → lifecycle of important entities
markdown
undefined
系统的构建逻辑，优先画图，其次配文字。
可以自由使用mermaid图：
  • 系统上下文 → 各角色交互关系（C4 层级1）
  • 组件图 → 核心模块和边界（C4 层级2）
  • 时序图 → 核心流程
  • 状态图 → 重要实体的生命周期
markdown
undefined

System Context

系统上下文

```mermaid graph LR User --> App App --> DB[(PostgreSQL)] App --> Queue[Redis] Worker --> Queue Worker --> ExtAPI[External API] ```
```mermaid graph LR User --> App App --> DB[(PostgreSQL)] App --> Queue[Redis] Worker --> Queue Worker --> ExtAPI[External API] ```

Components

组件

ComponentResponsibilityTalks to
APIHTTP handlers, authDB, Queue
WorkerBackground jobsQueue, ExtAPI
CLIAdmin commandsDB
组件职责交互对象
APIHTTP 处理器、鉴权DB、Queue
Worker后台任务Queue、ExtAPI
CLI管理命令DB

Key Flows

核心流程

```mermaid sequenceDiagram User->>API: POST /order API->>DB: insert order API->>Queue: enqueue process_order Worker->>Queue: dequeue Worker->>ExtAPI: submit Worker->>DB: update status ```

Rules:
- **Diagrams > text.** If you can draw it, draw it.
- **Tables > paragraphs.** Component lists, config options, API surfaces.
- **Pseudocode > real code.** `process(order) → validate → enqueue → respond` beats a 30-line function that'll change next week.
- **No folder trees.** They go stale immediately. Describe capabilities and boundaries instead.
- **Mention modules by name**, not by path. "The worker module handles..." not "src/worker/index.ts handles..."
```mermaid sequenceDiagram User->>API: POST /order API->>DB: 插入订单 API->>Queue: 入队 process_order Worker->>Queue: 出队 Worker->>ExtAPI: 提交请求 Worker->>DB: 更新状态 ```

规则：
- **图 > 文字。** 能画出来的就不要用文字描述。
- **表格 > 段落。** 组件列表、配置项、API 暴露能力都用表格。
- **伪代码 > 真实代码。** `process(order) → validate → enqueue → respond` 比下周就会改动的30行函数好用。
- **不要放文件夹树。** 很容易就过时，用能力描述和边界说明代替。
- **用模块名称指代，不要用路径。** 比如写「worker模块负责...」，而不是「src/worker/index.ts 负责...」。

docs/*.md — Other Material

docs/*.md — 其他材料

Anything useful for humans or agents:
  • GUIDE.md — walkthrough for common tasks
  • API.md — endpoint reference
  • DEPLOYMENT.md — how to ship it
  • DECISIONS.md — notable past decisions (lightweight ADR: what, why, when — no template ceremony)
所有对人类或Agent有用的内容：
  • GUIDE.md — 常见任务的操作指引
  • API.md — 接口参考文档
  • DEPLOYMENT.md — 部署方法
  • DECISIONS.md — 重要的历史决策（轻量级ADR：是什么、为什么、什么时候定的，不需要繁琐模板）

docs/plans/*.md — Specs & Execution Plans

docs/plans/*.md — 规范与执行计划

Filename convention: 
kebab-case-slug.md
(e.g. 
kalshi-hardening-2026-02-23.md
, 
loss-reduction-2026-02-23.md
). No SHOUTING. Date suffix for at-a-glance staleness detection. Living documents. Specs before code. Updated as work progresses.
markdown
undefined
文件命名规则：
短横线分隔的slug.md
（例如
kalshi-hardening-2026-02-23.md
、
loss-reduction-2026-02-23.md
），不要全大写，带日期后缀可以一眼看出是否过时。 属于活性文档，编码前先写规范，工作推进过程中持续更新。
markdown
undefined

[Feature Name]

[功能名称]

Goal

目标

One sentence.
一句话说明。

Context

背景

Why now? What's the current state? What's wrong with it?
为什么现在做？当前状态是什么？现存问题有哪些？

Design

设计

```mermaid graph LR ... ```
DecisionChoiceWhy
StorageSQLiteSingle machine, no need for Postgres
AuthAPI keyInternal tool, simplicity wins
```mermaid graph LR ... ```
决策选择原因
存储SQLite单机器部署，不需要Postgres
鉴权API key内部工具，优先简洁

Pseudocode

伪代码

``` on_request(order): validate(order.fields) enriched = fetch_market_data(order.ticker) if enriched.price > order.limit: reject("above limit") queue.push(enriched) return accepted(order.id) ```
``` on_request(order): validate(order.fields) enriched = fetch_market_data(order.ticker) if enriched.price > order.limit: reject("above limit") queue.push(enriched) return accepted(order.id) ```

Tasks

任务

  • Design approved
  • Implement core handler
  • Add validation
  • Write tests
  • Update ARCHITECTURE.md
  • 设计已通过
  • 实现核心处理器
  • 新增校验逻辑
  • 编写测试
  • 更新ARCHITECTURE.md

Open Questions

待解决问题

  • How to handle partial fills? → decided: treat as separate orders

Rules:
- **Spec first, code second.** Don't start implementation without an approved plan.
- **Keep them alive.** Check off tasks, update decisions, close questions.
- **Delete when done.** Completed plans can be archived or removed. They served their purpose.
- **One plan per feature/initiative.** Don't combine unrelated work.
  • 如何处理部分成交？→ 已决定：按独立订单处理

规则：
- **先写规范，再写代码。** 没有通过审批的计划不要开始实现。
- **保持活性。** 勾选完成的任务，更新决策，关闭已解决的问题。
- **完成后删除。** 已结束的计划可以归档或删除，它们已经完成了使命。
- **每个功能/项目单独一个计划。** 不要把不相关的工作合并到同一个计划里。

Writing Principles

写作原则

PrincipleInstead ofWrite
Show, don't describe"The system uses a pub/sub pattern for async communication between services"A mermaid diagram showing the flow
Tables over listsA bullet list of 8 config options with descriptionsA table with columns: option, type, default, description
Pseudocode over real codeA 40-line Go function
validate → enrich → enqueue → respond
Capabilities over paths"src/internal/worker/handler.go processes jobs""The worker processes background jobs from the queue"
Short sentences"The system is designed to handle the processing of incoming orders by first validating them and then...""Orders are validated, then queued for processing."
原则反面案例正确写法
展示，而非描述"系统使用发布/订阅模式实现服务间异步通信"用mermaid图展示这个流程
表格优先于列表带描述的8个配置项的无序列表包含配置项、类型、默认值、描述四列的表格
伪代码优先于真实代码40行的Go函数
validate → enrich → enqueue → respond
能力说明优先于路径"src/internal/worker/handler.go 处理任务""worker 处理队列中的后台任务"
短句优先"系统被设计为用于处理传入订单，首先校验订单，然后...""订单先经过校验，再入队等待处理。"

Lifecycle

生命周期

Before Work

工作前

Read 
AGENTS.md
, 
docs/ARCHITECTURE.md
, and any relevant 
docs/plans/*.md
. Understand what exists before changing anything.
阅读
AGENTS.md
、
docs/ARCHITECTURE.md
和所有相关的
docs/plans/*.md
文件，改动前先搞清楚现有逻辑。

After Work

工作后

Update what changed:
  • New component? Update 
    docs/ARCHITECTURE.md
    diagram.
  • Finished a plan task? Check it off in 
    docs/plans/*.md
    .
  • New convention or gotcha? Add to 
    AGENTS.md
    .
  • Plan fully done? Delete or archive it.
更新所有变更的内容：
  • 新增了组件？更新
    docs/ARCHITECTURE.md
    的架构图
  • 完成了一个计划里的任务？在
    docs/plans/*.md
    里打勾
  • 新增了约定或注意事项？加到
    AGENTS.md
    里
  • 计划全部完成？删除或归档

Keeper Mode

维护模式

When invoked explicitly as papyrus-maximus:
  1. Ensure structure — AGENTS.md exists, CLAUDE.md symlinked, 
    docs/
    and 
    docs/plans/
    exist
  2. Audit — are docs accurate? Do diagrams match reality? Any stale plans?
  3. Fix — update what you can. Create missing diagrams. Trim bloat.
  4. Flag — report what needs human attention
  5. Trim — AGENTS.md under 150 lines. README under 80 lines. Move overflow to 
    docs/
    .
显式调用papyrus-maximus时执行以下操作：
  1. 确保结构完整 — AGENTS.md存在，CLAUDE.md已创建符号链接，
    docs/
    和
    docs/plans/
    目录存在
  2. 审计 — 文档是否准确？图和实际逻辑是否一致？有没有过时的计划？
  3. 修复 — 尽可能更新内容，补全缺失的图，删掉冗余内容
  4. 标记 — 上报需要人工处理的内容
  5. 精简 — AGENTS.md控制在150行以内，README控制在80行以内，超出部分移到
    docs/
    目录下。