Today I Learned

1. Add the changes in a non-destructive way, such that we provide both the old and the new at the same time
2. Migrate the consumers from the old to the new
3. Delete the old stuff

1. expand
2. migrate
3. contract

import { Action, ActionPanel, closeMainWindow, List, popToRoot } from "@raycast/api";

interface Page {
  alias: string;
  name: string;
  icon: string;
  url: string;
}

// Pages you always want quick access to
const pinned: Page[] = [
  {
    alias: "1on1",
    name: "1on1 for Lukas",
    icon: "🪙",
    url: "https://www.notion.so/<organization-name>/<page-id>",
  },

  ...
];

// Temporary pages for current work — rotate as needed
const transient: Page[] = [
  {
    alias: "hardlimit",
    name: "Project Hardlimits",
    icon: "📄",
    url: "https://www.notion.so/<organization-name/<page-id>",
  },
];

function PageItem({ page }: { page: Page }) {
  return (
    <List.Item
      icon={page.icon}
      title={page.alias}
      subtitle={page.name}
      actions={
        <ActionPanel>
          <Action.OpenInBrowser
            url={page.url}
            onOpen={() => {
              popToRoot({ clearSearchBar: true });
              closeMainWindow();
            }}
          />
        </ActionPanel>
      }
    />
  );
}

export default function Command() {
  return (
    <List searchBarPlaceholder="Filter pages...">
      {transient.length > 0 && (
        <List.Section title="Transient">
          {transient.map((page) => (
            <PageItem key={page.url} page={page} />
          ))}
        </List.Section>
      )}
      <List.Section title="Pinned">
        {pinned.map((page) => (
          <PageItem key={page.url} page={page} />
        ))}
      </List.Section>
    </List>
  );
}

• どこまで正確に見積もりか
• どれほど見積もりに時間をかけるか

• 工数見積もりはあくまで見積もり。多くの場合は判断材料。一定の誤差は許容されるもの。
• 正確にしようと思うほど、見積もり自体の工数が膨らみ、最終的には実装するのと差異がない領域にまで近づく
• ラフな見積もりが大幅にはずれても、実装が近づいたらより解像度高く発覚し、その時点でもまた調整すればいい
• 意思決定が多いので、１つ１つに多大な時間をかけず、一定の精度でパンパン進める方が重要な場面も多い

• External quality → the end
• Internal quality → the means to sustain the end

• External quality — does what it should

  • Correct

    • Does the right thing
  • Usable

    • People can actually use it
  • Performant / Reliable

    • Does it consistently and well
• Internal quality — easy and safe to change

  • Easy to understand

    • Clear naming and structure
    • Well defined boundaries / separation of concerns
  • Easy to change

    • Small, focused, decoupled components
    • Changes are localized, don't ripple
  • Safe to change

    • Tests catch regressions
    • Changes are reversible / version controlled

1. Daily cronjob that regenerates the rss files (With an custom adapter per site)
2. Serve the rss files on localhost:8888

• 特定の API を実装
• 特定のページの UI を実装する
• 裏でガチャガチャ動くバッチジョブを実装する

• どう実装したらよいかわからない
• 仕様が曖昧でなかなか進まない
• 実装中の不明点が出てきた際に、それをチームとして相談・解決するまでのプロセスが明白ではない
• 色々な実装が分散していっていて、どのパターンに倣えばいいかわからない

• Layered Architecture を採用しているが各層の責務が曖昧であり、認識がチーム内でバラけている。ガイドラインを策定し、チーム内で共有することでパターンの統一へと向かっていける。
• 機能開発の進め方として、ざっくりとしてドキュメント１つが渡され、そこから四苦八苦しながらエンジニアが仕様・要求を明確にしながら進めていたが、要求を直接拾い上げていないので、開発着手までが遅かったり、着手しても満たすべき要求が明白じゃないまま進んで、何かを解決するものではない状態となってしまう事態などが起こってしまっている。そこで、自分らのフェーズに合わせて開発プロセス全体の構想を練って、PdM などの責務を明らかにし、重要である「要求がこれで本当に満たせるか？」などのための特別な確認ステップを設けたりして、潤滑かつ意義のある開発ができるように準備インエーブルする。
• AI 駆動開発における各種課題点を放置せず、仕組み化で回収し、速度と制度を向上させる。例えば、CI が失敗して人間がいつもその棟をエージェントに伝える伝言者のような役割を担っていたならば、エージェントの終了条件で CI に近しい条件を盛り込み、自己完結型までもっていくこと。また、AI エージェントによる不正確な修正や決定したパターンに準拠しない実装が発生した場合は、その場でだけ修正するのをやめて、全体の設定ファイルの更新やリンタールールの追加などの恒久作に皆が簡単に寄与できるようなしくみを作るなど。

• 課題の発見）「作り方」が欠如・未完成であることによる問題点を認知し、本当に問題かを共有して共同認知とする。
• 対応の決定）どのような「作り方」にすれば、その課題を解決できるのか考察する。実際やっていないため不確実性も高い中、一方通行なのか双方向なのかによって熟考度合いを調整し、対応案を決定する。
• 共有と実施）得られた学び・実施したい新しい「作り方」をチーム内でわかりやすく共有し、懸念・観点を拾い上げる。それを踏まえて解決策を練る直しつつ、導入していく。

• 型、表現形式、制約、命名など（一番分かりづらい部分）
• 提供されているインターフェース（API）の粒度（連携先はの３つの取得 API でやっと我々がほしい１つのデータが得られるなど）

• Translator -> 翻訳を担うパーツ。変換と聞いたら一番に思い浮かぶところ。
• Facade -> これは「見せかけ」「仮面」などを意味する単語である。インターフェースおの粒度を自分らの都合のようように見せ方を替えるパーツ。

• ~/feature_documents/ ディレクトリを作る
• プロジェクトの CLAUDE.local.md に以下のような指示を追記し、機能開発時に自動参照するように

When doing any kind of feature implementation, look at `~/feature_documents/` to see if there are any relevant feature documents.
If available, read that document and follow its instructions.
Also, if new decisions have been made about the feature or how to implement it that are specific to that feature, then update the document.
 
File format is `<date>-<content>` e.g. `2026-03-18-add-fuzzy-search`